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PREFACE 



The publication is intended for application programmers who are building menu 
interfaces to existing software. The Multics menu system consists of several commands and 
subroutines which can be used to create and manage menus. 

The major topics presented are: 

• A description of the terminal-management software that provides a means of dividing 
the terminal screen into different regions and of performing real-time editing. The 
terminal-management software is referred to in text as the "video system." 

• A description of the Multics commands and subroutines provided for creation and 
manipulation of video screens and creation and display of menus. 

• A description of the Multics I/O modules that support terminal-management functions. 

There are some manuals that are prerequisites to this one in that they describe tools 
that the application writer uses. The writer must be familiar with Multics I/O processing, 
commands, and subroutines. The manuals describing these are as follows: 

Multics Programmer's Reference Manual Programmer's Reference 

(Order No. AG91) 

Multics Commands and Active Functions Commands 

(Order No. AG92) 

Multics Subroutines and I/O Modules Subroutines 

(Order No. AG93) 



The information and specifications in this document are subject to change without notice. This 
document contains information about Honeywell products or services that may not be available 
outside the United States. Consult your Honeywell Marketing Representative. 
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The Programmer's Reference manual describes I/O processing and contains specific 
details for the use of screen terminals. The Commands manual contains the descriptions of 
commands that are referenced in text, such as exec_com. The Subroutines manual contains 
Multics subroutine descriptions. 

In addition, this publication assumes the programmer is familiar with PL/I, FORTRAN, 
or COBOL, and the Multics exec_com facility. (The exec_com examples in this document use 
Version 2 of exec_com.) The PL/I language is described in the PL/1 Language Specification, 
(Order No. AG94); the FORTRAN Language is described in the FORTRAN Reference 
Manual, Order No. AT58); the COBOL Language is described in the COBOL Reference 
Manual, (Order No. AS44). 

Significant Changes in CP51-02 

The video system now supports windows which do not extend across the full width of 
the screen. See Section 2 for details. 

The video system editor now accepts either upper or lower case letters when you use 
default escape sequences. See Section 4 for details. 

The "suppress_redisplay" field has been added to the line_editor_info structure. See 
Section 4 for details. 

The "window_call" command now accepts the "-width NC (-wid NO" control argument 
which specifies the width of . a region for a request See the "window_call" command in 
Section 5. 

The "change_window" and "create_window" arguments to the "window_call" command 
now accept the "-column C" and "-width NC" control argument. See Section 5. 

A "-line_speed (-Is)" control argument has been added to "window_call invoke". This 
allows you to specify the speed of your connection to Multics when you use the video 
system. If no "-line_speed" is specified, the current Iine_speed is used. See Section 5 for 
details. 



The "window_$edit_line" entry which allows applications to preload the video editor 
input buffer with a string, has been added to the window_ subroutine. See Section 6 for 
details. 



The "window_$write_raw_text" entry in the window_ subroutine now causes the cursor 
position to become undefined and sets the screenjnvalid window status flag. See Section 6. 
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Support for the "set_term_type" control order has been added to the tc_io_ I/O 
module. This control order or the set_tty command allows you to change the terminal type 
in a video session. 

Two new control arguments have been added to window_io_ switch. The n -first_column 
COL_NO" (control argument) is the column number on the screen where the window is to 
begin. The "-width N COLS" (control argument) is the number of columns in the window. 
See Section 7. 

The "set_output_conversion" and "get_output_conversion" control orders have been added 
to the window_io_ I/O module. The "get_output_conversion" control order obtains the 
current contents of the specified table. The "set_output_conversion" control order provides a 
table to use in formatting output to identify certain kinds of special characters. See Section 7 
for details. 

The "get_speciar and "set_special" control orders have also been added to window_io_. 
The "get_special" control order obtains the contents of the special_chars table currently in 
use. The "set_special" control order provides a table that specifies sequences to be substituted 
for certain output characters. See Section 7. 

A "get_editor_key_bindings" control order, which returns a pointer to the 
line_editor_key_binding structure describing the key bindings, has been added to window_io_. 
The "set_editor_key_bindings" control order has been changed. New fields have been added to 
the line_editor_key_binding structure. The control arguments "-name STR", "-description 
STR", and *'-info_pathname PATH" have been added to the io_call support set_editor_key_bindings 
control order. 

A new mode, "edited, A edited" suppresses printing of characters for which there is not 
defined Multics equivalent on the device referenced. See Section 7 for details. 
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SECTION 1 
INTRODUCTION TO THE MENU SYSTEM 



Multics is a large-scale, interactive system with a rich repertoire of commands, 
subroutines, tools and many interrelated subsystems. There are over 2,000 commands and 
subroutines alone. Effective use of the power this system has to offer is a specialty not 
every user masters. In many cases there is no reason to master it The majority of users 
have specific tasks to accomplish online and require only a small subset of the available tools. 
What they do need to know is what tools exist to get their job done most efficiently. The 
easier it is to figure that out, the better. Since many of these people are not trained in 
computer use, the system should be made easy to understand, provide flexibility and keep 
training at a minimum. The Multics menu system provides a means of accomplishing this. 

WHAT IS A MENU 

A menu is a list of options presented to the user on a video terminal. By typing a 
single key, designating an option choice, an action is performed. The most important feature 
the menu system has to offer is permitting the user who knows very little about the system 
to interact with the computer. No knowledge of commands is required since the system calls 
the command to do the job once the user indicates an option. All the actions required for a 
specific task are displayed on the terminal, selections are made, and the user is ushered 
through a given task by being prompted. You can design menus for all different levels of 
expertise and for any number of tasks. The easiest way to explain the menu system and to 
provide application ideas is to give examples of menus. The menu "Games" is shown here. 



Type a number and the corresponding action will be performed. 



GAMES 

1) Print a maze 

2) Print a large maze 

3) Play Football 

4) Play Basebal 1 

5) Do a Simulated Parachute Jump 



6) Play Star Trek 

7) Play Adventure 

8) Guess the Animal 

9) Play Backgammon 
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Imagine that the boxes in all the examples in this section are on terminal screens. This 
entire display is defined by the menu application. The screen is divided into two sections 
with the top part of the screen for menu display and the bottom part of the screen for user 
input/output. 

The user of this menu selects one of the options and the screen changes from the list 
of menu options to the description of a specific game. The screen is no longer divided into 
two parts and the user input/output section of the screen is expanded to full size. For 
example, if Option 5 is selected, the transactions appear as follows. In this example, 
user-typed input is preceded by an exclamation point 



Welcome to ' 


splat"- 


-the game that 


simulates 


a parachute 


jump. 


Try to 


open 


your chute at 


the last 


possible 


moment 


wi thout 


going 


splat 
















Select 


your 


own a 1 1 


tude? 


lyes 










What a 


ltitude (ft)? 


15000 




• 









When the user is finished playing this game, the screen goes back to the original menu 
display. Another option is selected or the user exits this particular menu. 

The next example is a menu for Tess True-Heart, a new terminal operator. Other than 
knowing how to login, Tess is a Multics novice. She needs to learn a little bit about the 
Multics system, i.e., how a command works, how to read her mail, and what manuals to read 
for details. Tess is at an advantage because the word processing system she worked on in her 
previous job also used menus, so she understands the concept. This is an important advantage 
for the application writer too. Since menus are used widely throughout the industry, people 
who use your menus will not find the concept a foreign one. As illustrated below, the menu 
system quite effectively "fences off" the Multics system into an understandable set of tools 
for personal use. The following example was written for Tess as an introduction to Multics. 
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1) 

2) 
3) 
k) 
5) 
6) 


<«MJLTICS TUTOR 1 AL>» 

What is a command? 

What commands do i use everyday? 

What commands are helpful but not essential? 

How do 1 read and send mail? 

What manuals are helpful for a beginner? 

Where do 1 go from here? 





As an example of the material in some of these options, Option 2 might discuss the 
list, help, and dprint commands. All the commands Tess is likely to use in her daily work 
are candidates for this option. 

The commands in Option 3 would be more sophisticated and might include exec_com 
and the absentee commands. 



Another example of a menu user is Percival C. Monday. Percy has no former 
experience with a computer and it is peripheral to his job. He uses it essentially as a filing 
system. This application is not unlike one intended for ticket agents at an airline counter, 
who use a computer strictly for one set of tasks. Percy must be able to read orders received, 

orocess orders file the nrriers r.hpf.lr the hnH&et a11/vatir»n /ovnonHitnToc rhv-mn « rionortm^t 

X- * ™ - —-——-, — .« v ~x. »x.w VH «.£, V v %.xxwt»»xwxx, WrtpilrtllkUlW, VXXIXX£V C* UW^ai tUlWil, 

maintain an inventory and change the inventory as orders are filled and shipments arrive. A 
menu to accomplish these tasks might look like this: 



<«MANUAL 0RDERS»> 
Enter the number corresponding to the function to be performed. 

1) List orders to be processed 

2) List orders processed this month 

3) List budget information 
k) Enter billing information 
5) Update Inventory 
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In the previous examples, the user went from a menu to the game "parachute jump" or 
to explanations of commands. In this example, Percy is going from the first menu to other 
menus. If Percy selects Option 5, the screen might look like this: 



1) List of parts available 

2) Additions made to inventory list 

3) Deletions made to inventory list 



Percy selects one of the options in this list and performs the appropriate action. 

The first three examples are for inexperienced users and the advantages for such persons 
are obvious. However, the menu system can be tailored for the experienced user as well. The 
next example is a manager's application. The manager is Gloria VanDerMint, who has five 
people working for her in the research and development department In addition to heT 
development work, she has a number of tasks that must be performed routinely, so you can 
incorporate them all into one menu. You can set up a number of data bases containing 
information such as weekly status reports from her unit, and from these she writes the unit 
status report or performance appraisals, and updates schedules. You may also include the 
memo command to remind her when performance appraisals and status reports are due. 
Another convenient command to incorporate is calendar, which reminds her of meetings and 
trips. Gloria's menu is given below. 



<«The Good, The Bad, and The Boring>» 



6) Personal Schedules 

7) Produce Schedules 

8) Performance Appraisal Form 



1) 


Read memos 


2) 


Send memos 


3) 


Calendar 


k) 


Modify calendar 


5) 


Unit Status reports 
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An additional menu for more complex tasks is one that offers a choice of programming 
procedures. This is helpful for people who have programmed on other systems but not on 
Multics and discusses the languages and editors available, tells them about formatting programs 
explain compiling on Multics and discusses debugging tools. It might contain the following: 



<«Programming Procedures»> 



1) Name Your Language 

2) Enter New Program 

3) Update Existing Program 



h) Format Your Program 

5) Execute Your Program 

6) Debug Your Program 



THE CONNECTION BETWEEN THE MENU SYSTEM AND THE VIDEO SYSTEM 

In the next section, the video system is introduced. A more detailed discussion is 
presented in Section 4. Menu application programs use the video system to manage the 
display on the terminal screen. As noted above, all these examples have the screen divided 
into portions which have different uses. Since we cannot physically divide the screen, we 
must do it logically. This is the job of the video system, and this terminal management is 
required to support the menu software. 
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SECTION 2 
INTRODUCTION TO THE VIDEO SYSTEM 



The advent of comparatively low cost video terminals has brought a new dimension to 
the computing industry. Today's video terminals have many more capabilities than hard copy 
ones. Real-time editing, and higher speed communication are available and the display can 
change easily and quickly with varied functions. 

The video system is a terminal-independent presentation interface. This means that an 
application can run on any supported terminal and produce essentially the same display. The 
video system enables the application writer to divide the terminal screen into "windows" to 
partition the display. The menu writer must have a thorough understanding of windows; how 
to invoke the video system (the first step in the process of creating windows), how to revoke 
the video system, and how to create, destroy, change and clear windows. This section 
discusses design considerations involved in using windows and covers the video material most 
important to the menu application writer. For a more detailed description of the features of 
the video system, see Section 4 of this manual. 

WHAT IS A WINDOW 

A window is an area of the screen whose contents can be manipulated without affecting 
the rest of the display. For example, the user may scroll the contents of a segment in one 
window without moving the contents of the segment displayed on any other part of the 
screen. 



Each window behaves like an individual video terminal. Many possible operations may 
be performed on a window. These include displaying characters, moving the cursor, erasing 
lines, inserting lines, and others. Characters are normally sent to a window via the Multics 
I/O system and the iox_ subroutine (see the Multics HO and Subroutines manual, Order 
No. AG93). Additional operations specific to the capabilities of video terminals are 
performed by the window_ subroutine (described in Section 6), which is analogous to iox_. 

A window is a rectangular region of the screen. The screen can be divided into several 
windows that can be viewed simultaneously but the windows may not overlap. The number of 
line and columns in each window can vary. A window can be one column wide or it can 
extend across the full width of the screen. 

The size of a window is specified at the time the window is created. Character 
positions are identified by line and column with the origin (or home) located at the upper 
left hand corner of the window. Each window has its own home, line 1, column 1, and 
character positions are always with respect to the home of the specific window. 
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If you want to create a window from command level, use the window_call command 
with the create_window argument You can also use the window_create entry to the window_ 
subroutine to create a window on the terminal screen. (Refer to the description of window_ 
subroutine later in this manual.) 

The command syntax for creating windows from command level is: 

window_call create_window -io_switch WINDOW 
{-line L -column C -height NL -width NC} 

window_call, wdc 

this command provides a command interface to the video system 

create_window, crwd 

this argument creates a new window on the screen 

-io_switch WINDOW 1 -io_switch 

WINDOW 1 specifies the window associated with the given I/O switch. 

-line L 

specifies the line number on the screen where the window is to begin. To create a 
window beginning on the third line, use -line 3. If -line is not specified, the default is 
line 1. 

-column C, col C 

specifies the column number on the screen where the window is to begin. To create a 
window beginning in the third column, use -column 3. If -column is not specified, the 
default is column 1. 

height NL, -hgt NL 

specifies the height of the window. To create a window 10 lines high, use -height 10. If 
-height is not specified, the default is the remainder of the screen. 

-width NC, -wid NC 

specifies the width of the window. To create a window 20 columns wide, use -width 20. 
If -width is not specified, the default is the remainder of the screen. 

Figure 2-1 is an example of three different types of windows that you can create on a 
screen. You can create a window called WINDOW_l that is 20 columns wide and 10 lines 
high. This window begins on the third line and the second column. To create WINDOW_l 
(shown in Figure 2-1), type the following command line: 

wdc crwd -is WIND0W_1 -line 3 -column 2 -height 10 -width 20 

You can also create a second window on the same screen called WINDOW_2. This 
window is 3 columns wide and begins in column 25. Since line and height are not specified, 
the window begins in line one and fills the remainder of the screen. To create WINDOW_2 
(shown in Figure 2-1), type: 

wdc crwd -is WIND0W_2 -column 25 -width 3 
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You can create a third window on the screen called WINDOW_3. This window is 14 
columns wide and 7 lines high. This window begins at line 17 and column 32. To create 
WINDOW_3 (shown in Figure 2-1), type: 

wdc crwd -is WIND0W_3 -line 17 -column 32 -height 7 -width ]k 

Refer to Section 5 for more information on these commands and other commands used 
by the menu and video software. 
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Figure 2-1. Windows on a Screen 



Window Capabilities 

Thp rana hili ties riefinprl frvr a winHnw nrp trrriiiTV»H intn fivp catPOTYriec- Tw:itinnin«r the 

cursor, selective erasure, scrolling, selective alteration, and miscellaneous. Window operations 
may be performed with the window_call command or by a call to the window_ subroutine. 
These are described in Sections 5 and 6 respectively. 
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POSITIONING THE CURSOR 

Each window has its own logical cursor. This cursor exists even when the terminal's 
cursor is performing operations in another window. The position of this cursor may be 
explicitly changed in a variety of ways. The cursor can be positioned absolutely or relatively. 
Absolute positioning can be to the home position or to an arbitrary line and column. 
Relative positioning can be up, down, left, or right any number of positions. The cursor also 
moves as characters are displayed in the window. 

SELECTIVE ERASURE 

Selective Erasure (or clearing) means changing some region of the display so that no 
visible characters appear in that region, without changing any other area of the window. Most 
video terminals are capable of at least some selective erase operations. Where possible, the 
video system uses any special terminal features present to clear regions. When the terminal 
has no useful feature for clearing the specified region, regions are cleared by overwriting 
them with spaces. This can be a rather slow operation. 

A region is a rectangle contained within a window. Like a window, it has an extent 
(height and width) and a position. All erasure operations pertain to regions. The definition of 
the region may be explicit (position and extent supplied in the call) or implicit (the region 
begins at the current cursor location, or at home). The cursor is always left at the origin of 
the region. 

A window may be cleared: entirely, from the home to the end of the window; from 
the current cursor position to the end of the current line in the window; from the current 
cursor position to the end of the window. An arbitrary region may also be cleared. 

SCROLLING 

A window may be scrolled up or down by a given number of lines. Scrolling up means 
moving lines up from the bottom of the window - deleting lines at the top, and adding new, 
blank lines at the bottom. Scrolling down means moving lines from the top of the window 
down, deleting at the bottom and adding at the top. Scrolling is usually done automatically 
by the video system when output fills the window, but it can also be requested explicitly. 

SELECTIVE ALTERATION 

Selective alteration means adding or deleting characters or lines in the middle of the 
window. When characters (or lines) are added, adjoining characters (or lines) move over to 
make room for the new ones. When characters (or lines) are deleted, characters (or lines) 
move in to fill up the gap. This differs from selective erasure, which only affects the 
characters erased. 



MISCELLANEOUS 

Among other things, entries are provided in the window_ subroutine and the 
window_calI command to sound an audible alarm, to obtain the current cursor position, and 
to output an arbitrary character sequence. 
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Window/Video Commands and Subroutines 

The command supporting windows is introduced here but is explained in detail in 
Section 5 of this manual. 

window_call 

is the command interface to the video system. This is used in exec_com applications 
while the window, subroutine is used in PL/ 1, ft_window_ is used in FORTRAN, and 
cb_window_ is used in COBOL applications. 

The subroutines supporting windows and the video system are described in detail in 
Section 6 of this manual and are as follows: 

video_utils_ 

activates and deactivates the video system. 

video_data_ 

is a data segment containing information about the video system. 

window_ 

is the subroutine interface to the video system. It is the corresponding subroutine to the 
window_call command. 

Attaching the Video System 

You must check whether or not the users of the proposed menu have the video system 
turned on. It is not likely that novice users would do this initially but it might be included 
in a project start_up. If it is on, it is important that you leave it alone. Do not turn it on 
again or you will get an error message. If you have determined that the video system is 
turnw on, you should then have your application use the space allocated to the 
user_input/output window instead of the whole screen. Thus, if the user creates a separate 
window for interactive messages, an application should not use that space. Using the space 
allocated to the user_io window respects the user's explicit wishes and prevents violation of 
the restriction against using two overlapping windows at the same time. 

When the video system is invoked, the entire screen is covered by a window associated 
with the user_i/o I/O switch. Determine how much of the screen you have and divide up 
that amount for use by your application. Since terminals vary in the length of the screen, 
and some users already may have some lines devoted to their own video display, you are 
probably dealing with less than 20 lines, so design with that in mind. As long as there are 
eight or ten lines available for user input/output that should be sufficient 

The first step then is determining whether or not the video system is turned on and, if 

not, turn it on. This should be included at the beginning of all menu applications. The 

following is the exec_com example. The lines are numbered only for the purpose of 
explanation and should not be included in your exec_com. 



2-5 CP51-02 



1 Sset already_video £[io attached user_terminal_] 

2 Si f 6 [not &(already_video)] 

3 &then window_call invoke 

k &set first_lTne &[window_cal 1 get_f i rst_l ine] n_lines 

&[window_cal 1 get_window_height] 

where: 

1. determines whether or not the video system is attached to the user's terminal. 

2. turns it on if it isn't already on. 

3 invokes window_call initiating the window environment, 

4. sets the lines for the window. This is part of the first step because when you revoke 

the video system at the end of the exec_com, you must set the screen to the size it 

was originally. 

The following is the PL/ 1 example that does the same thing. Declare statements are included 
in the example. Again, the lines are numbered for the purpose of explanation and the 
numbers should not be included in your program. 

del (addr, null) builtin; 

del iox_$control entry (ptr, char (*) , ptr, fixed bin (35)); 

del com_err_ entry options (variable); 

del iox_$user_io ptr ext static; 

del video_uti ls_$turn_on_logi n_channel entry 

(fixed bin (35) » char (*) ) ; 

del video_data $terminal_iocb ext static ptr; 

del ME char (32) init (" ties t_prog ram") static options (constant); 

del code fixed bin (35) 5 

del al ready_video bit (1); 

del reason char (128) ; 

1 %include wi ndow_control_i nf o; 

2 del 1 my_window_info 1 i ke window_posi tion_info; 

3 my_window_info.version = wi ndow_pos i tion_i nf o_vers ion^l ; 
it if video_data^$terminal_iocb = null () then do; 

5 call video_uti 1 s_$turn_on_logi n_channel (code, reason); 

6 if code ~= then do; 

call com_err_ (code, ME, ""a", reason); 
return; 
end; 

7 already_video = "0"b; 
end; 

8 else already_video = "l"b; 

9 call iox_$control (iox_$user_io, "get_window_i nfo", 
addr (my_window_info) , code); 

10 if code "= then do; 

call com_err_ (code, ME, "get_window_i nfo") ; 
return; 
end; 
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where: 

1. includes appropriate structure declarations 

2. declares an automatic copy of window info 

3. sets the version number of window info 

4. determines if the video system is not activated then does 4 through 6 

5. turns on the video system and 

6. if there is an error, reports it to the caller and quits 

7. makes a note to the effect that video was invoked by this program 

8. goes to here if the video system is already activated (video was not activated by this 
program) 

9. gets the current size and location (beginning line number) of the user_i/o window 

10. prints error message j 

Detaching the Video System 

At the end of the exec_com, you have to turn off video and leave things as you found 
them. First, is the exec_com example for revoking the video system. The lines are numbered 
only for the purpose of explanation and these numbers should not be included in your 
exec_com. 

1 &if & (already_video) 

2 &then window_call change_wi ndow -line & (f i rst_l i ne) 

-height & (n_l ines) 

3 Seise window_call revoke 

where: 

1. determines whether or not video was activated by this exec_com. 

2. if video was activated by another exec_com, then user_i/o window is returned to 
previous size and it is cleared. 

3. otherwise, the window interface to the video system is deactivated and the user_i/o 
window goes to full screen. 

The PL/ 1 example: 

1 if already_video then do; 

2 call video_uti 1 s_$turn_of f_login_channel (code) ; 

if code ^=0 then do; 



end; 
end; 
else do; call iox_$control (iox_$user_io, "set_window_info", 

Mui \"'/_" ' iiuun i hi v/ 9 uwuc/ 9 

if code ~=0 then do; 



end; 
end; 
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where: 

1. determines whether or not video was activated by this program. 

2. if video was previously attached, then the user_i/o window is returned to its previous 
size. 

3. if the video system was activated by this program, it is then deactivated and the 
user_i/o window goes to full screen. 

Design Requirements for Windows 

In Section 1, all of the examples used two windows: the top window which displayed 
the menu itself and the bottom window which was for user input/output. As part of the 
menu design process, you decide ahead of time how the display will look and from that 
determine the number of windows that will be advantageous. 

As an example, you may have the screen divided into three windows. The top window 
could display the status of the user with the user name, a description of what he's doing and 
a clock. The middle window could contain various menus and could grow or shrink 
depending on the selection made. The bottom window could be for unformatted' output and 
for typing in input 

The number of windows technically permitted is quite large and probably more than you 
will need. Knowing how many functions are to be performed, you should carefully select the 
number of windows to be used by an application. It is possible on a 24 line terminal to 
have 24 windows but rarely, if ever, would that be useful. Each window would be too small 
and the screen would be too cluttered. Practically, there should not be more than five. In 
the examples in Section 1, there are lines marking the division between top and bottom 

* windows. This is a trailer line specified in the exec_com or program. It is not necessary, but 
does make the delineation obvious and aids readability. Windows may not overlap. Each 

| window has its own extent (height and width) and location (the position of its home on the 
screen). Windows can change their extent and location as long as they never overlap. The 
initial extent and location of a window is determined in the attach description of the window. 

Window Operations 

The rest of this section discusses the operations of window_call and window_ that are 
most essential. These include: create, change, destroy, and clear. Specific examples are given 
for exec_com and PL/ 1 applications. 
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CREATE WINDOW OPERATION 

Now you need to define windows and this is done with arguments to window_call or 
with the entry points of the window_ subroutine. The first action discussed is create_window. 
Part of the creation process is the naming of windows. Windows are associated with iox_ 
I/O switches. The "name of the window" is just the name of the switch, or as it is 
sometimes called, the iocb name. Since many Multies commands and subroutines make use of 
the standard switches user_io, user_input, error_output, and user_output, it is usually necessary 
to have these switches connected to some window. This is done by window_eall invoke or 
video_utils_$turn_on_login_channel. By convention, the bottom window of the screen is used 
for user_i/o. 

Important Window Requests 

Before a window can be created you must decide on its starting line number as 
discussed above in "Attaching Video" and its length (in number of lines). As mentioned 
earlier, it is customary to get space for a new window from the user_i/o window and to 
position the new window at the top of the user_i/o window. Therefore, one of the first 
things to do is find out where the user_i/o window is. Once this is known you must 
determine just how high, in lines, the new window must be and shrink the user_i/o window 
by that amount. It is a good idea to always check to make sure there is enough space left 
in the user_i/o window to allow meaningful communication once it has been shrunk. In our 
examples we will insist on at least a five line user_i/o window. 
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To do all that has been discussed so far in an exec_com, we would have the following: 

£- stored in the default value segment as the_menu. 

&set io_start &[window_cal 1 get_f irst_l ine] 
6set io_height &[window_cal 1 get_window_height] 
Sset menu_height £[menu_descr ibe thejnenu -height] 

5- Now calculate the new positions of both windows. 

£set menu_start £(io_start) 

£set io_start £[plus £(io_sfcart) £ (menu_height) ] 

Sset io_height & [minus £(io_height) £ (menu_height) ] 

£- The label referenced below would, of course, need to be 

6- defined and would include an appropriate error message. 

&if 6 [n less £(io_height) 5] 

£then £goto USER_l/0_T00_SMALL 

£- Now shrink user_i/o 

window_call change_window -line £(io_start) -height &(io_height) 

&- And define the new window, called able 

window_call create_window -io_switch able -line £ (menu_start) -height 
£ (menu_height) 

The real work of creating the new window above was done by the window_call 
command with the create_window argument This command created the necessary iox_ I/O 
switch attachments to make "able" an I/O switch which describes a video system window that 
occupies the first "menu_height" lines of what was user_i/o. 
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THE PLII EXAMPLE 

A window can be created either at command level or from a PL/ 1 subroutine. To do 
the same thing in PL/I you would use the following code fragment: 

/* Get the variables initialized. We assume the menu has */ 
/* been created and the requirements for the menu are */ 

/* stored in the menu_needs structure (see menu_ for del) */ 

% include window_control_info; 

del 1 io_window_info like (window_posi tion_info) ; 

del 1 menu_wi ndow_info like (wi ndow_posi tion_i nf o) ; 

io_window_ info. vers ion = window_posi tion_info_version_l ; 
call iox_$control (iox_$user_io, "get_window_info", addr 

(io_window_info) , code); 

if code ^= then do; 

process the error 

end; 
menu_wi ndow_i nfo = io_window_i nf o; 

/* Now calculate the new positions of both windows. */ 

menu_wi ndow_i nfo.or igi n. 1 i ne = io_window_inf o.or i gi n. 1 i ne; 
io_wi ndow_i nfo.or igi n. 1 ine = io_wi ndow_i nfo.or i gi n. 1 i ne 

+menu_wi ndow_i nfo. extent. height; 
io_window_i nfo. extent. height = io_window_i nfo. extent. height 

-menu_window_i nfo. extent. height; 
if io_window_i nfo. extent. height < 5 
then do; 

if code "= then do; 

process the error 

end; 
end; 

/* Now shrink user_i/o */ 

call iox_$control (iox_$user_io, "set_wi ndow_i nf o", addr 
(io_window_info) , code) ; 
if code ~= then do; 

process the error 

end; 

/* And define the new window */ 

call wi ndow_$create (video_data_$terminal_iocb, addr (menu_window_i nfo) , 
menu_w i ndow_ i ocbp , code) ; 
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CHANGE WINDOW OPERATION 

In the above examples we have seen that it was necessary to change or shrink the 
user_i/o window in order to create a new window. When we discuss destroying windows 
below we will see a need to expand the user_i/o window to recover the space freed by the 
destruction of a window. 

Command level changes are done with the window_call keyword change_window. In 
PL/ 1 the changes are made by the set_window_info control order. In general this will be 
preceded by a get_window_info control order and some calculations. 

DESTROY WINDOW OPERATION 

Once a window is no longer needed it must be destroyed, i.e., the I/O switch must be 
closed and detached thus freeing up the space on the screen that was occupied by the 
window. In addition, this space should be returned to some active window so that it can be 
used. If the freed space is adjacent to the user_i/o window it should be consumed by that 
window, but it can be added to any adjacent window. In our examples we will add it back 
to user_i/o. 

To reverse the effects of the exec_com window creation example above we would have: 

&- destroy the able window 

6- and let user_i/o have the space back 

&set io_start 6 (menu_start) 

Sset io_height 6 [pi us & (tnenu_height) & (io_height) ] 

&set menu_start menu_height 

window_call change_wi ndow -line &(io_start) -height &(io_height) 

In PL/I we would have: 

/* destroy the able window */ 

call window_$destroy (...); 
if code A> - then do; 

process the error 

end; 
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/* and let user_i/o have the space back */ 

io_window_i nfo.or igi n. 1 ine = menu_window_info.or igin.l ine; 
: o_w i ndow_i nf o . extent .height = menu_wi ndow_i nf o . extent . he i ght 
+io_window_info. ex tent. height; 

call iox_$control (iox_$user_io, "set_window_info", 
addr (io_window_info) , code); 
if code "= then do; 

process the error 

end; 



CLEAR WINDOW OPERATION 

Another very useful operation is the clear_window operation. This clears the entire 
window to all spaces and leaves the cursor positioned at the upper left hand corner of the 
window. There are other clearing operations, but this one is the simplest and most useful. 

From command level we can clear the user_i/o window by: 
window_call clear_window 

If we had wanted to clear, say the able window, we would have included the -io_switch 
control argument specifying able as the window to operate on. 

This same effect, clearing the able window of our examples, can be accomplished from 
FL/I by: 

call window_$clear_window (menu_window_iocbp, code); 
if code ~= then do; 

process the error 

end; 



The clear_window operation is useful when an application wants to start with a clean 
slate in the user_i/o window. For example, before printing out a description of some menu 
option it might be desirable to clear the user_i/o window. 
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OTHER USEFUL OPERATIONS 

Once window status is set, any operation performed on that window (except for a create 
or destroy operation) returns the status code video_et_$window_status_pending until the status 
is reset To reset the status, perform a get_window_status control order on the window 
switch. Refer to "Control Operations" for window_io_ later in this manual. 

There are many other operations that can be performed on windows using the video 
system. These are all described in the window_call command in Section 5 or in the window, 
subroutine description in Section 6 or the control orders or modes of the window_io_ I/O 
module in Section 7. 
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SECTION 3 
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This section discusses the use of function keys and the building of a menu application. 
It includes a sample exec_com, and PL/I programs. FORTRAN and COBOL programmers 
refer to Section 8 and Section 9, respectively. 

GUIDELINES FOR FUNCTION KEYS 

A set of keys that are integral to the menu system are the function keys. These are 
used to get information, move from one menu to another, or to exit from a menu and 
return to Multics command level. The reason that the function keys are used at all is to 
reserve the numbers for the options and also to eliminate the need to include these functions 
in every list of options in every menu. Ease of use is enhanced when the function keys are 
doing the same thing from application to application. The following example shows the 
definitions of the function keys in the "Games" menu. 

Press Fl - Gives definitions of the function keys 

Press F2 - Returns to the first menu 

Press F3 ~ Goes to the previous menu 

Press Fl* - Returns to Multics command level 



If there are no function keys on the terminal, then the user could type specially 

assigned keys in sequence. In the following example the escape key has been chosen in 

conjunction with a letter that is related to the action performed. The selection would then 
be: 

ESC d - Gives definitions of the function keys 

ESC f - Returns to the first menu 

ESC p - Goes to the previous menu 

ESC r - Returns to Multics command level 



Since not all terminals have function keys, you must include a call to 
ttt_info_$function_key_data (described in Multics Subroutines and HO Modules, Order No. 
AG93) in your program, which will return information about the terminal being used. This 
information covers whether or not there are function keys and how many there are. 

For those terminals without function keys, or which do not have enough, you must 
designate key* to be used in their place. It is helpful to the end user if the first of these 
keys is a "special" key such as the escape key. This should be followed by a regular key that 
is somewhat related to the action to be performed. You can use a single key, but the 
advantage of two in sequence is that it does not interfere with the option numbers or letters 
that have been used. The sequence can also be more than two keys, but the longer it is the 
greater the chance of typing errors. 
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Summary of function key recommendations: 

• Assign the same meaning to specific keys for every menu. 

• Include a call to ttt_info_$function_key_data in your program. 

• There is no command level interface to ttt_info_$function_key_data so this 
cannot be done with exec_com. 

If function keys are not available, follow the above suggestions plus: 

• Use a combination of characters such that the first character is not the same 
as any menu option character. A suggestion is using a special key (not @ or 
#) such as <ESC> in conjunction with a character related to the action 
performed. For example, <ESC> p for previous menu, or <ESC> r for 
returning to command level. 

• Do not use numbers or single letters as they are reserved for options. 

• Do not use two digit numbers because only the first digit is "heard" and an 
option would therefore be selected. In other words, if you have a function 
numbered 12 only the first digit is processed so option 1 would be selected. 

THE EXEC_COM EXAMPLE 

There are four ways in which menu applications may be built one using exec_com and 
written in the Multics command language; the others using PL/ 1, FORTRAN or COBOL 
programs. The exec_coms provide a quick and easy way to implement very simple menu 
applications whereas PL/I, FORTRAN or COBOL programs provide for more powerful and 
robust ones. The Multics menu system provides commands and subroutines to facilitate either 
type of implementation. 

Below is an example of an exec_.com interface to the menu system. It is a very simple 
application and it illustrates how you can begin. The example is a document menu for 
everyday office use. It is called "Document System". The user will be able to enter, edit, 
display, print, list or delete documents. The last option available is to exit the document 
system. So, there are seven options in all and they will be displayed in the top window. 
Since you will probably want them displayed in the fewest number of lines possible, make 
space in this window for 6 lines allowing for the headers, the trailers, and the list of menu 
options printed in two columns. The area from line seven to the end of the screen is the 
user_i/o window. To see how the standard I/O switch attachments change when you use an 
exec_com to create a menu, refer to Appendix A, especially Figure A-3. Line numbers are 
used in this example to indicate new lines, e.g., line 18 is all one line in the exec_com and a 
new line does not occur till the number 19 appears. Line numbers should not be included in 
your exec_com. 
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1 Sversion 2 

2 &trace off 

&- First we will see if the video system is enabled 

&- in the users process. This is done by checking 

&- to see if the I/O switch user_terminal_ is 

&- attached. If it isn't we invoke the video 

&- system. We need to do this so that we can later 

&- return the user to his/her normal environment. 

3 Sset al ready_video &[io attached user_terminal_] 
k &if £[not £ (already_video)] 

5 Sthen window_call invoke 

6- Now we will create our demonstration menu. In 

5- real applications this menu would most likely be 

£- saved in some value segment containing other menus. 

6 menu_create main -option "enter new document" 
-option "edit old document" -option "print document on 
terminal" -option "print document on printer" -option 
"list documents" -option "delete document" -columns 2 
-header "<« DOCUMENT SYSTEM >»" -centerjieaders 
-trailer "-" -trailer "USE FUNCTION KEY 1 TO EXIT" 
-trailer "-" -center_trai lers -pad "-" 

6- Here we determine where the windows will go. 

6- What we will attempt to do is split the user_i/o 

&- window into two windows. The top window is named 

&- using a unique name to avoid conflict with other 

&- I/O switch names in the process and will contain 

5- the menu. The bottom window will be user_i/o. 

6- This split of user_i/o is done to allow this 

&- application to run while other video applications 
&- windows exist on the screen. 

7 Sset menu_start &[window_cal 1 get_f i rst_l ine] 

8 Sset menu_height &[menu_descr ibe main -height] 

9 Sset io_start &[plus & (menu_start) 6 (menu_height) ] 

10 Sset io_height &[minus [window_call get_window_hei ght] & (menu_height) ] 

&- We must have at least 5 lines left in user_i/o. 
&- This is an arbitrary limit that this exec_com 
6- will enforce. 

11 &if &[nless &(io_height) 5] 

12 &then Sdo 

13 Sprint There is not enough room on the screen to run. 
1 It Squ i t 

15 &end 

&- Now establish the window to be used to display 
&- the menu. It takes its space on the screen from 
6- user_i/o, so first shrink user_i/o. The menu 
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£- window is given a name using the unique active 
£- function to avoid conflicts with I/O switch names 
£- already in existence. 

16 window_ca!l change_window -line £(io_start) -height £(io_height) 

17 £set menu_switch £ [unique] .menu 

18 window_call create_window -io_switch 6 (menu_swi tch) -line 
£ (menu_start) -height £ (menu_height) 

£- We are now ready to display the menu and get a 

6- choice. We must display the menu each time 

6- through the loop due to the fact that 

£- menu_get_cho i ce will modify the menu display in 

£- the window. We will set a local exec_com 

£- variable to the choice made just in case we want 

6- it in the future (in this example we don't, but 

6- i ts a good i dea anyway) . 

19 £ label GET-CHOICE 

20 menu_display main -io_switch £ (menu_swi tch) 

21 £set~choice £[menu_get_choice main -io_switch £ (menu_swi tch)] 

£- Now that we have either (1) a valid menu choice 
£- in the form of a decimal integer, or (2) a 
£- function key selection in the form "F" followed 
£- by the function key number, let's perform the 
£- requested action. 

22 £goto CHO I CE-£ (choice) 

£- This choice is "enter a new document." It will 

£- first create the new document and then enter ted 

£- to allow entry of the text. Before doing 

£- anything, this action, like all others, will 

£- clear the user_i/o window. This gives a feeling 

£- of starting some new action that we want at this 

£- point (this is done for all actions). 

23 £label CH0ICE-1 

2k window_call clear_window 

25 io control user_i/o resetjnore 

26 do "create ££l;ted -pn ££1" [response "new document name:"] 

27 £goto GET-CHOICE 

£- This choice is "edit an old document." It will 
£- enter ted for editing of the requested document. 

28 £label CH0ICE-2 

29 window_call clear_window 

30 io control user_i/o resetjnore 

31 ted -pn [response "old document name:"] 

32 £goto GET-CHOICE 
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6- This choice is "print document on terminal." It 
&- will just print the specified document in the 
&- user_i/o window. 

33 &label CHOICE-3 

34 window_call clear_window 

35 io control user_i/o reset_more 

36 print [response "document name:"] 1 

37 Sgoto GET-CHOICE 

&- This action is "print document on printer." It 
£- will simply enter a dprint request of the 
&- specified document. 

38 Slabel CHOICE-4 

39 window_call clear_window 

kO io control user_i/o reset_more 

k] dprint [response "document name:"] 

k2 Sgoto GET-CHOICE 

&- This is the "list documents" action. It will 
£- simply list the names of all of the documents 
&- defined. Our convention for document naming is 
6- simple - any single component segment name will 
&- do. 

43 Slabel CHOICE-5 

hk window_call clear_window 

kS io control user_i/o reset_more 

*fb 1 i s i. »■ — name —primary 

kj Sgoto GET-CHOICE 

6- This is the "delete document" action. It deletes 
6- the document specified by the user. 

48 Slabel CHOICE-6 

49 window_call clear_window 

50 io control user_i/o reset_more 

51 delete [response "document name:"] 

52 &goto GET-CHOICE 

£- This is the action for function key #1. This 

5- action exits the document subsystem. At this 

6- point we will destroy the menu window and either: 

5- (1) return the user_i/o window to its former 

6- state, or (2) revoke the window system entirely. 
&- This choice is based on whether the video system 
6- was in effect when we started this exec_com. 

53 &label CH0ICE-F1 
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$U window_call delete_window -io_switch 6 (menu_swi tch) 

55 6 i f & (already_video) 

56 Sthen &do 

57 window_call change_window -line & (menu_start) -height 
&[plus 6 (menu_height) & (io_height)] 

58 window_call clear_window 

59 &end 

60 &else window_call revoke 

61 &quit 

6- One last thing to check for are undefined 
&- function keys. For these we will simply ring the 
&- bell (in the video system tradition that's what 
6- it does for undefined control character input 
&- sequences) . 

62 &label CHO I CE-& (choice) 

63 window_call bell 
61. Sgoto GET-CHOICE 

THE PL/I EXAMPLE 

Below is the PL/ 1 example setting up the same menu, Document System. Your first 
reaction may be that it is far more complicated and much longer than the exec_com example. 
If the document system menu were going to stay, this simple it probably wouldn't be 
reasonable to do it in PL/I. But if the menu is going to be enhanced with more capabilities 
and power, PL/I is the better approach. You can add a great deal of versatility and correct 
errors with a PL/I application, something that just cannot be done with exec_com. 

mdl : 

proc ; 

/* Automatic */ 



dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 



choice fixed bin; 

choices (6) char (30) var; 

code fixed bin (35); 

f key bit (1) al igned; 

headers (1) char (30) var; 

key_shif t_idx fixed bin; 

menu_io ptr init (null); 

menu_io_swi tch_name char (32); 

menu_ptr ptr; 

my_area area (1+095) ; 

1 my_menu_format like menu_format; 

1 my_menu_requi rements 1 ike menu_requi rements; 

1 new_window_info 1 ike window_posi tion_info; 

reason char (512) ; 

term_type char (32) ; 

trailers (2) char (30) var; 

1 user _io_window_ info 1 ike window_posi tion_info; 

video_was_already_on bit (1) aligned; 
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/* Based */ 

del 1 fkey_data like function_key_data based (function_key_data_ptr) ; 

/* Bui 1 tin */ 

del (addr, empty, length, null) builtin; 

/* Conditions */ 

del cleanup condition; 

/* Entries */ 

del com_err_ entry () options (variable); 
del ioa_ entry () options (variable); 
del ttt_info_$function_key_data entry 

(char J*), ptr, ptr, fixed bin (35)); 
del unique_chars_ entry (bit (*)) returns (char (15)); 
del user_info_$terminal_data 

entry (char (*) , char (*) , char (*) , fixed bin, char (*) ) ; 
del video_uti ls_$turn_off_login_channel entry (fixed bin (35)); 
del video_uti ls_$turn_on_login_channel entry (char (*) , fixed bin (35)); 

/* External */ 

del video_data_$terminal_iocb pointer external; 

/* Static */ 

del ALTERNATE_F1_STRING char (2) static options (constant) init ("d,) ; 

/* ESC a */ 
del ME char (3) static options (constant) init ("mdl") ; 
del MIN_USER_IO_HEIGHT fixed bin static options (constant) init (5); 
del USER_I0 char (8) static options (constant) init ("user_i/o") ; 

video_was_already_on = (video_data_$terminai_iocb "» null); 

on cleanup call terminate_sys () ; 

/* Set up the menu. */ 

/* Invoke the window system if it's not. already invoked. */ 

if ~video_was_a1ready_on then do; 

call video_uti ls_$turn_on_login_channel (code, reason); 
if code •"•= tnen 

call quit (code, reason); 
end; 

call window_$clear_window (iox_$user_io, code); 
if code "= then 

call quit (code, USERJO); 

/* Create the menu. */ 
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choices (1) = "enter new document"; 

choices (2) = "edit old document"; 

choices (3) = "print document on terminal"; 

choices W) = "print document on printer"; 

choices (5) = "list documents"; 

choices (6) = "delete document"; 

headers (1) = "<« DOCUMENT SYSTEM >»"; 
trailers (1) = "USE FUNCTION KEY 1 TO EXIT"; 
trailers (2) = "-"; 

call user_info_$terminal_data ((""), term_type, ("") , (0), ("")); 
call ttt_info_$function_key_data (term_type, addr (my_area) , 
function_key_data_ptr, (code)); 

if code "= then 

call quit (code, "Unable to determine terminal type") 

/* See if we have to use an escape sequence for Fl */ 

if fkey_data. highest < 1 then do; 

trailers (1) = "USE ESC-q TO EXIT"; 

free fkey_data in (my_area) ; 

function_key_data_highest = 1; 

allocate fkey_data in (my_area) set (f unction_key_data_ptr) ; 

fkey_data. version = function_key_data_version_l ; 

fkey_data.seq_ptr = addr (ALTERNATE_F 1_STRING) ; 

fkey_data.seq_len = length (ALTERNATE_F 1_STRI NG) ; 

do key_shif t_idx = to 3; 

f key_data . home . sequence_l ength 

(key_shift_idx) = 0; 
f key_data. lef t.sequence_l ength 

(key_shift_idx) = 0; 
fkey_data. up. sequence_l ength 
(key_shift_idx) = 0; 
fkey_data. right. sequence_l ength 

(key_shift_idx) = 0; 
f key_data .down . sequence_l ength 

(key_shift_idx) = 0; 
f key_data . f unct i on_keys . sequence_l ength 

(0, key_shift_idx) = 0; 
f key_data . f unct i on_keys . sequence_l ength 
(1 , key_shift_idx) = 0; 
end; 

fkey_data.function_keys.sequence_index (1, KEY_PLAIN) = 1; 
fkey_data.f unct ion_keys.sequence_l ength (1, KEY_PLAIN) = 
1 ength (ALTERNATE_F 1_STR I NG) ; 
end; 

my_menu_format. vers ion = menu_format_version_l ; 
my_menu_format.max_width = 80; 
my_menu_format.max_hei ght = 6; 
my_menu_format.n_columns = 2; 
my_menu_format.center_headers = "l"b; 
my_menu_format.center_trai lers = "l"b; 
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my_menu_format.pad = "0"b; 
my_menu_format.pad_char = "-"; 

my_menu_requirements. vers ion = menu_requirements_version_l ; 

/* Now we can create the menu. */ 

call menu_$create (choices, headers, trailers, addr 
(my_menu_format) , 
MENU_OPTION_KEYS, addr (my_area) , addr (my_menu_requirements) , 
menu_ptr, code) ; 
if code ~= then 

call quit (code, "Unable to create menu."); 

/* Now carve the menu I/O window out of the user_i/o window. 
This program insists that the user_i/o window must be at 
least 5 lines high after this is done. The menu I/O window 
is given a unique name so that this program can be invoked 
recursively. */ 

user_io_window_info.version = window_posi tion_info_version_l ; 
call iox_$control (iox_$user_io, "get_window_info", 

addr (user_io_window_info) , code); 
if code A = then 

call quit (code, USERJO); 

if user_io_window_ info. height 

< my_menu_requirements.l ines_needed + MIN_USER_IO_HEIGHT then 
call quit (0, "Window ""user_i/o"" is too~sma 1 1 . ") ; 

new_window_info. version = window_posi tion_info_version_l ; 
new_window_info. 1 ine = 

user_io_window_info.l ine + my_menu_requirements. 1 ines_needed; 
new_window_info. width = user_io_window_info. width; 
new_window_info. height = 

user_io_window_ info. height - my_menu_requirements. 1 ines_needed; 
call iox_$control (iox_$user_io, "set_window_info", 
addr (new_window_info) , code); 
if code "= then 

call quit (code, "Unable to shrink window ""user_i/o"".") ; 

menu_io_swi tch_name = "menu_i/o_" || unique_chars_ ("0"b) ; 
call iox_$f ind_iocb (menu_io_swi tch_name, menu_io, code); 
if code A - then 

call quit (code, "Unable to get I0CB pointer for menu window."); 

new_window_info. 1 ine = user_io_window_info. 1 ine; 
new_window_info. height = my_menu_requi rements. 1 ines_needed; 

call window_$create (video_data_$terminal_iocb, 

addr (new_window_info) , menu_io, code); 
if code ~= 0~then 

call quit (code, "Unable to create the menu_i/o window."); 
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/* Now that we have the window system all set up we can go ahead and 
display the menu and start processing. */ 

call menu_$display (menu_io, menu_ptr, code); 
if code ~= then 
.call quit (code, "Unable to display menu."); 

/* Now start processing input from the user. */ 

do while ("l"b) ; 

/* Get an option number or function key value from the user. */ 

call menu_$get_choice (menu_io, menu_ptr, function_key_data_ptr , 
fkey, choice, code); 

/* Perform an action depending on the user's selection. */ 

if code A = then 

call quit (code, "Unable to get choice."); 
if fkey then 

if choice = 1 then do; 
call terminate_sys (); 
if video_was_al ready = on then 

call window_$clear_window (iox_$user_io, (0)); 
goto EXIT; 
end; 

else call window_$bell (menu_io, (0)); 
else do; 

if choice = 1 then 

call create_document () ; 
else if choice = 2 then 

call edi t_document (); 
else if choice = 3 then 

call display_document () ; 
else if choice = ^ then 

call pr int_document 0; 
else if choice = 5 then 

call 1 ist_documents 0; 
else if choice = 6 then 

call delete_document () ; 
else call window_$bell (menu_io, (0)); 

end; 
end; /* do whi le */ 

EXIT: 

return; 

/* procedures for options */ 

create_document: 
proc () ; 

call ioa_ ("To be provided."); 

3-10 CP51-02 



end create_document; 

sd: t_document: 
proc () ; 

call ioa_ ("To be provided."); 
end edi t_document; 

display_document: 
proc () ; 

call ioa_ ("To be provided."); 

end display_document; 

pr int_document: 
proc () ; 

call ioa_ ("To be provided."); 

end pr int_document; 

1 ist_documents: 
proc () ; 

call ioa_ ("To be provided."); 

end 1 ist_documents; 

del ete_document: 
proc () ; 

call ioa_ ("To be provided."); 

end delete_document; 

/* internal procedures */ 

/* This procedure is called whenever we must leave the 
subsystem we have set up (if an error occurs or the 
user wants to leave). It rearranges things back to 
the way they were before. */ 

terminate_s'ys: 
proc () ; 

if menu_io ~= null () then 

call window_$destroy (menu_io, (0)); 
i f v i deo_was_a 1 r eady_on then 

call iox_$control (iox_$user_io, "set_window_info", 
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addr (user_io_window_info) , (0)); 
else call video_uti ls_$turn_off_1ogin_channel ( (0) ) ; 

end terminate_sys; 

qui t: 

proc (code, explanation); 

del code fixed bin (35) 5 
del explanation char (*) ; 

call terminate_sys () ; 

call com_err_ (code, ME, explanation); 

go to EXIT; 

end quit; 

% include iox_dcls; 

%page; 

% include window_dcls; 

%page; 

% include function_key_data; 

%page; 

% include menu_dcls; 

Ipage; 

^include window_control_info; 

end md 1 ; 
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SECTION 4 
VIDEO SYSTEM DETAILS 



This section describes the Multics Video System. The Multics Video System is an 
upwards compatible extension to the Multics Communications System. The basic features of* 
the Multics Video System are: 

• Dividing the user's terminal into one or more windows. Windows are described 
in detail in Section 2 of this manual. 

• A powerful real-time editor for input lines. The erase and kill characters take 
effect as soon as they are typed. Additional characters allow the user to delete 
words and to retrieve deleted text 

• Flexible control over output When a window is full of output it can scroll 
(removing lines from the top of the window, adding new ones to the bottom), 
or wrap (output begins at the top of the window, optionally clearing the 
window first). 

• MORE Processing. The video system pauses when a window is full of output 
until the user indicates that the window has been read. This is an extension to 
End Of Page processing. The user can also choose to discard unseen all 
pending output 

REAL-TIME EDITING 

Real-time editing is markedly different from usual Multics editing. All editing requests 
take effect immediately. The screen changes to show the effect of the characters or lines 
deleted. In addition, the set of editing characters expands to include several control 
characters. 

Control characters are characters entered using the control key.. The control key is a 
key that acts like the shift key. By itself it generates no characters; it is used to change the 
meaning of some other key. When the key "A" is typed while the control key is held down, 
the character sent by the terminal is control A, which is written as A A. The control 
characters are the first 32 ASCII characters, 000 through 037 octal. 

Alphabetic characters are given in capitals, but either an upper or lower case letter (as 
for N or n) can be used with default escape sequences. If an upper case letter is used with 
a user-defined sequence, both the upper and lower case keys must be bound in order for 
both keys to work. The letters ESC represent the escape key. For ESC F, you would press 
the escape key, release it and type an f or F. 
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Although most Multics users keep the system default erase (#) and kill (@) symbols, 
the video system recognizes and then assumes the values of any erase and kill characters that 
may have been set via the set_tty command. 

The Erase Character 

The erase character removes the character to the left of the cursor. The cursor moves 
to the left, and exactly one character is deleted. This is different from usual Multics editing 
where an erase character typed after white space deletes all whitespace, and otherwise deletes 
all characters from a column position. The erase character is settable for each window. In 
addition, the DEL character (\177) and the backspace character (\010) are always erase 
characters. 

The Kill Character 

The kill character deletes the entire line to the left of the cursor. The cursor then goes 
back to the beginning of the line. Again, this happens immediately. The deleted line is 
saved, and can be recovered. See "Retrieving Deleted Text" below. The kill character is 
settable per-window. 

The Line Editor 

Additional editing is possible using sequences of one and two characters. The 
two-character sequences all begin with the ASCII ESC character, ( A [, octal 033), which is not 
the same as the Multics input escape character ("\"). 

MOVING THE CURSOR 

The line editor can move the cursor forward or backward within the current line while 
repositioning the cursor either a character at a time or a word at a time. A word is an 
unbroken string of uppercase and lowercase alphabetics, numerals, underscores, backspace 
characters, and hyphens. (This is the default definition of a word, which can be changed 
with the set_token_delimiters order, described in the window_io_ writeup.) The cursor can 
also move explicitly to the beginning or the end of the current line. The requests that 
perform these actions are listed under "Other Editor Requests" below. 

DELETING CHARACTERS AND WORDS 

The line editor can delete a single character or an entire word at a time. Various 
editing requests described below can delete the character or word immediately to either the 
left or the right of the cursor. The deleted text (only words, not characters) is saved and 
can be retrieved. For example, typing ESC DEL (or ESC followed by the current erase 
character) deletes the word to the left of the cursor. The word is saved on the kill ring (see 
below). 
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RETRIEVING DELETED TEXT 

Text deleted by the word and line kill characters is saved, and can be restored. The 
text is saved on a kill ring. A kill ring is a set of kill slots. Each siot holds deleted text. 
Successive word kills share one kill slot, so if several words are deleted one after another, all 
of them will be retrieved by a single retrieve command. 

Deleted text is saved with previously deleted text if two delete characters are typed in 
succession. If intervening characters are typed, the kill ring is rotated: a new slot is selected 
to hold saved text 



Text is entered when the user types text followed by a carriage return. Each input line 
is added to the kill ring. This provides editing of the previous input line. 

The following control characters are used to retrieve deleted text: 

A Y (or yank) retrieves deleted text from the kill ring. This is the only way 

to recover from an erroneous kill character. 

ESC Y can be typed only after either A Y or ESC Y. It deletes the text just 

retrieved, without saving it on the kill ring, rotates the ring (to the 

next most recently killed text) and retrieves the text from the new top 
slot 



The following example is given in triplets. The first line shows what the user types, the 
second line shows what one line of the display looks like afterwards, and the third line (or 
lines) shows the kill ring. The top item on the kill ring is at the top of the column. 

User Types: This is a sentence 
Display is: This is a sentence 
Kill Ring: <empty> 

NOTE: The kill ring is empty because the user has just invoked the video system. 

User Types: ESC DEL 
Display is: This is a 
Kill Ring: sentence 

One word is deleted, and it begins the kill ring. 

User Types: ESC DEL 
Display is: This is 
Kill Ring: a sentence 
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Another word is deleted; it is merged into the same kill slot 

User Types: an example sofa 

Display is: This is an example sofa 
Kill Ring: a sentence 

User Types: ESC DEL 

Display is: This is an example 

Kill Ring: sofa 

a sentence 

This deleted word is not merged, because there has been typing since the last kill command. 
There are now two slots on the kill ring. 

User Types: of ~Y 

Display is: This is an example of sofa 

Kill Ring: sofa 

a sentence 

The top kill slot is yanked back. 

User Types: ESC Y 

Display is: This is an example of a sentence 
Ki 1 1 Ring: a sentence 
sofa 

The kill ring is rotated, the previously yanked contents are deleted from the line, and the 
new top item from the ring is yanked to replace it 

If a carriage return were typed at the end of "This is an example of a sentence", the 
kill ring would then contain a new slot containing the entire input line. 

Other Editor Requests 

Alphabetic characters are given in capitals, but either an upper or lower case letter 
(ESC F or ESC f) can be used. The following control characters are also recognized by the 
line editor: 

*L Clears the window and redisplays the input line. 

aq "quotes" the next character, causing it to have no special 

meaning. This is useful for entering control characters. It serves 
some of the same purposes as the input escape character (\). 

*F moves the cursor forward one character. 

ab moves the cursor backward one character. 

ESC F moves the cursor forward one word. 

ESC B moves the cursor backward one word. 
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AA moves the cursor to the beginning of the current line. 

AE moves the cursor to the end of the current line. 

AD deletes the current character (deletes forward). 

DEL, # deletes the character to the left of the cursor (deletes backward). 

ESC D deletes the current word (deletes forward). 

ESC DEL, ESC # deletes the word to the left of the cursor (deletes backward). 

ESC C capitalize initial word. 

ESC U capitalize word. 

ESC L lower case word. 

ESC T twiddle word. 

By default, no other control characters have meaning. If any are typed, the only action 
they cause is an audible alarm. You can create additional editor requests by writing PL/1 
programs that conform to a standard calling sequence (see "Writing Editor Extensions"). 

The set of characters used to define a word for control characters such as ESC F can 
be changed via the set_token_characters control order. See the description in the window io 
I/O module later in this manual. - ~ 

Writing Editor Extensions 

The video system provides a full input line editor, including the ability to edit in the 
middle of the line. Of course, there are many potential editor functions that people might 
like to use (see the Emacs Text Editor Useit Guide Order No. CH27), and not all of these 
are provided. Rather than attempt to anticipate every possible editor request, the video system 
allows users who are familiar with PL/1 to write their own editor requests and associate 
sequences of keystrokes (key bindings) with these requests. 

The key binding mechanism can be used for a wide variety of applications. Since editor 
requests are executed immediately by single or multiple keystroke sequences, highly interactive 
facilities can be built into the input line editor. 

LINE EDITOR ROUTINES 

Editor request routines are PL/I programs that conform to a standard calling sequence 
The request procedure is given complete control of the input buffer and can add or delete 
characters or modify the current contents of the buffer. The video system editor's redisplay 
facility manages all display updates; the individual editor .routines need no knowledge of the 
video enviroment or the screen contents. 
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A library of editor utility routines is provided (see "Editor Utilities"). These can be 
called by user-written editor routines to perform such actions as insertion and deletion of 
text from the buffer, manipulation of the kill ring, and manipulation of words within the 
input buffer. 



A line editor routine is declared as follows: 
USAGE 

del twiddle_words entry (pointer, fixed bin (35)); 
call twiddle_words (1 ine_edi tor_info_ptr , code); 
ARGUMENTS 

line_editor_info_ptr 

is a pointer to the line_editor_info data structure (described below). 



code 



is a standard status code. (Output) If the status code returned by the editor routine is 
error_table_$action_not_performed, the editor will ring the terminal bell to indicate that 
the editor routine was used improperly. Any other code will reported in a more drastic 
manner, via the sub_err_ mechanism. 



The 
follows: 



line_editor_info structure (declared in window_line_editor.incl.pll) is declared as 



del 1 1 i ne_edi tor_info 

2 version 

2 iocb_ptr 

2 repeti tion_count 

2 flags, 

3 return_f rom_edi tor 

3 merge_next_ki 1 1 

3 old_merge_next_ki 1 1 

3 last_ki 1 l_direction 

3 numarg_given 

3 suppress_redi splay 

3 pad 

2 user_data_ptr 

2 cursor_index 

2 1 ine_length 

2 input_buffer 

2 key_sequence 



aligned based (1 ine_edi tor_info_ptr) , 
char (8) , 

pointer, /* to current window */ 
fixed bin, 



bit(l) 
bit(l) 
bit(l) 
bit(l) 
bit(l) 
bit(l) 
bit (30) 



unal igned, 
unal igned, 
unal igned, 
unal igned, 
unal igned, 
unal igned 
unal igned, 



pointer, /* for 
fixed bin(21) , 
fixed bi n (21) , 
character (1024) 
character (128) ; 



user state info */ 



unal igned; 



del 1 ine_editor_input_l ine char (line_edi tor_inf o.l ine_length) based (addr 
(1 i ne_ed i tor_i nf o . i nput_buf f er) ) ; 

del 1 ine_editor_info_version_2 char (8) static options (constant) init 
("lei00002") ; 
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STRUCTURE ELEMENTS 



version 

is string for this structure. (Input) The current version string, "lei00002", is the value of 
the variable Iine_editor_info_version_2, declared in the same include file, 

iocb_ptr 

is the pointer to the current window. (Input) 

repetition_count 

is the value of the numeric argument specified by the user, and is undefined if no 
numeric argument was specified (i. e., numarg_given flag = "0"b). (Input) 

return_from_editor 

is a flag which is set by the editor routine if the editor invocation is to be terminated 
and the input line returned to the caller. The input buffer is redisplayed before the 
buffer is returned to the caller, unless overriden by the line_editor_info.suppress_redisplay 
flag. 

merge_next_kill 

is a flag which should be set when text is deleted and added to the kill ring if 
subsequent deletions are to be added to the same kill ring element (Input/Output) This 
flag is managed by the editor utility routines. If the editor utility routines are used for 
all input buffer modifications, the user-written editor routine need never set this flag. 

old_merge_next_kill 

is an internal editoT state flag and should not be modified, (not used) 

last_kill_direction 

direction of last kill (forward or backward). 

numarg_given 

is "l"b (i.e. true) if a numeric argument was supplied by the user via ESC-NNN or A U. 

suppress_redisplay 

is a flag that stops the redisplay of the input buffer when line_editor_info.return_from_editor 
is set 

pad 

reserved for future use. 

user_data_ptr 

points to a user data structure which the video system ignores, other than passing this 
pointer to requests that follow. 

cursor_index 

is the index of the character in the input buffer on which the cursor is currently 

located. (Input/Output) This index must be updated if characters are added or deleted 

before the cursor, or the cursor is moved by the editor routine. The cursor index must 
be no larger than one greater than the input_line_length. If the editor utility routines 

are used for all input buffer manipulations, the cursor_index will be updated 
appropriately. 
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linejength 

is a count of the number of characters in the current input line. (Input/Output) This 
variable must be updated if any characters are inserted or deleted from the input buffer. 
The value of the linejength variable must always be non-negative, and must never be 
larger than the length of the input buffer. If the line editor utility routines are used for 
all input buffer manipulations, the linejength variable will be updated automatically. 

inputjroffer 

is a character string containing the current input line. (Input/Output) Any manipulations 
may be performed on this string by the editor routine. It is recommended that the 
editor utility routines be used for all insertions and deletions to ensure that the various 
state variables and flags remain consistent The line_editorJnputJine variable can be 
used to address the valid part of the input buffer as astring. 

key_sequence 

A character string that contains the sequence of key strokes that invoked this editor 
routine. 

Window Editor Utilities 

As was mentioned above, a library of editor utility routines is provided for the benefit 
of user-written editor routines. Some operations can be performed simply by a user-written 
editor routine. For example, to position the cursor to the end of the line, simply set the 
cursorjndex variable to one greater than the value of the linejength variable. However, 
most actions are more complex than this and it is recommended that the editor utility 
routines be used to perform most operations. The following is a description of these routines. 
In all cases, line_editorJnfo_ptr is the pointer to the editor data structure that is supplied as 
an argument to user-written editor routines. 

del window_editor_uti 1 sj> insert Jext entry (ptr, char (*) , code); 
call window_edi tor_uti 1 sj> insert J:ext (1 ine_edi tor Jnfo_ptr , "text", 
code) ; 

Inserts the supplied character string into the input buffer at the current cursor 
location. If the string is too large to fit in the remaining buffer space, the code 
error_table_$action_not_performed is returned. This routine updates the linejength 
field of the line_editorJnfo structure, and the cursorjndex if necessary. 

del window_editor_uti lsj>delete_text entry (ptr, fixed bin, code); 
call window_edi tor_uti 1 sj>deletej:ext (1 ine_edi tor J nfo_ptr , count, 
code) ; 

Deletes a specified number of characters (supplied by the variable count) from the 
input buffer at the current cursor location. If there are not enough characters 
remaining between the cursor and the end of the line, error jableJ>action_not_perf ormed 
is returned and no characters are deleted. The linejength component of the 
line_editorJnfo_structure is updated, and the cursorjndex if necessary. 
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del w i ndow_ed i tor_ut i 1 s_$de 1 ete_text_save entry 

(ptr, "fixed bin, bit(l), code);" 
cal 1 window_edi tor_uti ls_$delete_text_save 

(1 ine_editor_infc_ptr, count, ki i l_di recti on, code); 

This entrypoint is idenentical to delete_text, but the deleted text is added to the kill 
ring. The kill_direction flag is used during kill mergng to decide whether the killed 
text will be concatenated onto the beginning or end of the current kill ring element. 
"l'*b is used to specify a forward kill (e.g. FORWARD JDELETEJVORD), "0" a 
backward kill. 

del window_edi tor_uti 1 s_$move_f orward entry (ptr, fixed bin, code); 

call window_edi tor_uti ls_$move_f orward (1 ine_edi tor_info_ptr, count, code); 

Advances the cursor forward a specified number of characters (supplied by the 
variable "count") in the input line. If there are not enough characters between the 
cursor and the end of the line, error_table_$action_not_performed is returned. 

del window_edi tor_uti ls_$move_backward entry (ptr, fixed bin, code); 
cal 1 window_edi tor_uti ls_$move_backward 
(1 ine_editor_info_ptr, count, code); 

Moves the cursor backward a specified number of characters (supplied by the variable 
"count") in the input line. If there are not enough characters between the cursor and 
the end of the line, error_table_$action_not_performed is returned. 

del window_editor_uti ls_$move_forward_word entry (ptr, code); 

call window_edi tor_uti ls_$move_forward_word (1 ine_edi tor_info_ptr, code); 

Updates the cursor_index to a position after the next word (or token) in the input 
line. A word is defined via the editor's set of token delimiters, set via the 
set_token_delimiters control order. 

del window_edi tor_uti 1 s_$move_backward_word entry (ptr, code); 
cal 1 window_edi tor_uti ls_$move_backward_word 
(1 ine_edi tor_info_ptr , code); 

Updates the cursor_index to a position before the preceeding word (or token) in the 
input line. A word is defined via the editor's set of token delimiters, set via the 
set_token_delimiters control order. 

del wi ndow_edi tor_uti 1 s_$get_top_k i 1 l_r ing_element entry 

(ptr, char (*) , fixed bin 35)) 
cal 1 window_edi tor_uti ls_$get_top_ki 1 l_r ing_element 

(1 ine_edi tor_info_ptr, text code), 

Returns the top kill ring element. 
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del wi ndow_edi tor_uti ls_$rotate_ki 1 l_r ing entry (ptr, fixed bin (35)) 
cal 1 window_edi tor_uti ls_$rotate_ki 1 l_ring 
(1 ine_edi tor_i nfo_ptr , code) 

Rotates the kill ring. 

End-Of-Window Processing 

When output has filled a window, old lines must be removed to make way for new 
ones. This is usually done by scrolling old lines off the top of the window. But for windows 
that cannot be scrolled (usually because the terminal cannot scroll) it is possible to move the 
cursor back to home, and output new lines overwriting the old ones. This is known as 
wrapped output A variation on wrapped output is to clear the window after moving the 
cursor home. The action taken when a window is full is controlled on a per-window basis by 
any one or the following more_mode modes: 

• clear the window is cleared, and output starts at the home position. 

• fold output begins at the first line and moves down the screen a line at a 
time replacing exisitng text with new text Prompts for a MORE response 
when it is about to overwrite the first line written since the last read or 
MORE break. 

• scroll lines are scrolled off the top of the window, and new lines are printed 
in the space that is cleared at the bottom of the screen. This is the default 
for all terminals capable of scrolling (i.e., those terminals that have the 
capability to insert and delete lines). 

• wrap output begins at the first line and moves down the screen a line at a 
time replacing existing text with new text Prompts for a MORE response at 
the bottom of every window of output This is the default for terminals 
incapable of scrolling. 

For more information, refer to window_io_ in Section 7. 

MORE PROCESSING 

As lines are displayed in the window, old lines are scrolled off the top of the window 
or otherwise removed. When output would cause a line to be removed that has been 
displayed since the most recent input, it is assumed that the user may not have had a chance 
to read it, and MORE processing occurs. The question "MORE?" appears on the screen, and 
no further output occurs until the user indicates that pending output is to be either displayed 
or discarded. MORE processing is controlled by the "more" mode, which is enabled by 
default 

Output resumes if the user strikes CR, and is discarded if the user strikes DEL. The 
characters used can be set by a control order. Type ahead characters are not seen by MORE 
processing. The response to MORE must be typed after the prompt appears. All other 
characters are buffered to be returned later. 
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When output is discarded, the video system simply ignores output until a getjine or 
get_chars call is made, a "reset_more" control order call is made, or the window is cleared, 
or the cursor is moved to home. WARNING: a prompt sent just before a get_line call will 
not be printed if output is discarded, unless the prompting program first issues a 
"reset_more" control order (or otherwise resets more processing). 

OUTPUT BUFFERING 

The video system sometimes buffers output internally, sending it to the terminal when 
certain internal conditions are satisfied. All buffered output is sent to the terminal whenever 
an input call is made (e.g., window_$get_echoed_chars). This ensures that all output, including 
prompts, is seen by the user before input is read. An application program that calls window, 
entrypoints directly should take this buffering into account to perform correctly. If it is 
necessary to send output to the terminal when no read request is to be done (e.g., displaying 
an incremental message during a long computation), the application should call window_$sync 
on the I/O switch after the output has been requested (e.g., via a call to window_$overwrite_text). 
See the description of window_$sync in the window_ subroutine description later in this 
manual. 

SUBROUTINE INTERFACE 

The video system provides .a standard set of operations for windows available through 
the window, subroutine. Some terminals are not capable of supporting all of these operations. 
In addition, the standard iox_ operations of getjine, get_chars, and put_chars are provided. 
Some manipulations on windows are made via iox_ control orders (the window_io_ description 
in Section 7). Some of these are compatible with existing tty_ control orders. The iox_ and 
tty_ subroutines are both described in the Multics Subroutines and 110 Modules manual, 
Order No. AG93. Other manipulations control features that are specific to the window 
environment 

The iox_ operations are defined in terms of the more primitive window_ operations. 
For example, the window_ primitive, window_$overwrite_text, can only display a string of 
characters that fit on a terminal line. The iox_$put_chars wraps long strings onto multiple 
lines, and displays control characters with the conventional octal representation. For this 
reason special care must be taken when using window_ applications on a window when iox_ 
operations are in use as well. For more details see the description of the reset_more control 
order in the window_io description in Section 7. 

COMMAND LINE INTERFACE 

The command level interface to the video system is the window_call command. This 
command can perform most of the operations on a window supported by window_ directly 
from command level, ine window_caii command is described in Section 5. 
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SECTION 5 






This section contains descriptions of the commands used by the menu and video 
software, presented in alphabetical order. 
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menu create menu_create 



Name: menu create 

SYNTAX AS A COMMAND 

menu_create menu_name {-control_args} 

FUNCTION 

The menu_create command creates a menu description, assigns it a specified name, and stores 
the description in a segment The menu description may be used with other menu commands, 
active functions, and subroutines. 

ARGUMENTS 

menu_name 

is the name assigned to the menu when it is stored. 

CONTROL ARGUMENTS 

-pathname PATH, -pn PATH 

is the pathname of the segment in which the menu is stored. Menus are stored in value 
segments. If the specified segment does not exist, the user is asked argument). The value 
suffix is assumed. If this control argument is omitted, the user's default value segment 
(>udd>Project_id>Person_id>Person_id.value) is used to store the menu. 

-brief, -bf 

means that if the segment specified by the -pathname control argument does not exist, it 
is to be created without querying the user. 

-option STR -opt STR 

specifies a menu option. The options appear in the menu in the order given. At least 
one option must be supplied. If STR contains blanks or special characters, it must be 
quoted. 

-header STR, -he STR 

specifies a line of header. All header lines specified appear in the menu in the order 
given. If STR contains blanks or special characters, it must be quoted. 

-trailer STR, -tr STR 

specifies a trailer line. All trailers appear in the menu in the order given. If STR 
contains blanks or special characters, it must be quoted. 

The remaining control arguments control the format of the menu. All are optional. 

-columns N, -col N 

where N is a positive decimal integer, sets the number of columns in the menu to N. 
The default is one column. 

-center_headers, -ceh 

causes all headeT lines to be centered. 
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menu_create menucreate 



-no_center_headers, -nceh 

causes header lines to be flush left This is the default. 

-center_trailers, -cet 

causes all trailer lines to be centered. 

-no_center_trailers, -ncet 

causes trailer lines to be flush left This is the default. 

-optionjceys STR, -okeys STR 

specifies the keystrokes to be associated with each option. Each character in STR is 
associated with the corresponding option, so that if it is typed, the corresponding option 
is selected. There must be at least as many characters in STR as there are options. If 
this control argument is not given, the string 

"123456789ABCDEFGHUKLMNOPQRSTUVWXYZ" is used. 

-pad C 

where C is one character, specifies the padding character for centering. The default is 
the space character. 

-linejength N, -11 N 

where N is a positive decimal integer, specifies the line length for the menu. If not 
supplied, the line length will be the line length of the user's terminal at the time the 
.. command is invoked. 

ACCESS REQUIRED 

The user must have r and w access on the value se^^e"* 

EXAMPLES 

The following example sets up a small menu named compile. 

menu_create compile -pn [pd]>temp -pad = -he "SAMPLE MENU" -tr = -ceh -cet 
-columns 2-11 78 -opt "Compile with No Options" 
-opt "Symbol Table" -opt "Profile Info" 



Creates a menu that looks like this: 



=SAMPLE MENU== 



(1) Compile with No Options (3) Profile Info 

(2) Symbol Table 
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menu delete menu_delete 



Name: menu_delete 

SYNTAX AS A COMMAND 

menu_delete menu_name {-control _arg} 

FUNCTION 

The menu_delete command deletes a menu description from a specified value segment 

ARGUMENTS 

menu_name 

is the name that was assigned to the menu when it was stored. 

CONTROL ARGUMENTS 

-pathname PATH, -pn PATH 

is the pathname of the value segment in which the menu is stored. If this control 
argument is not given, the user's default value segment is searched for the menu. The 
value suffix is assumed. 
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menu_describe menu describe 



Name: menu_describe 

SYNTAX AS A COMMAND 

menu_descr ibe menu_name {-control_args} 

SYNTAX AS AN ACTIVE FUNCTION 

[menu_descr ibe menu_name -control_args] 

FUNCTION 

The menu_describe command prints or returns information about a menu. 

ARGUMENTS 

menu_name 

is the name that was assigned to the menu when it was stored. 

CONTROL ARGUMENTS 

-count, -ct 

returns the number of options defined in the menu. 

-height 

returns the height of the menu. 

-pathname PATH, -pn PATH 

is the name of the value segment in which the menu has been stored. The value suffix 
is assumed. If this control argument is omitted, the user's default value segment is 
searched for the menu. 

-width 

returns the width of the menu. 

NOTES 

When used as an active function, exactly one of -count, -height, or -width must be given. 

As a command, any number are allowed. If none are given, all attributes are displayed. 
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menu_display menu_display 



Name: menu display 

SYNTAX AS A COMMAND 

menu_display menu_name {-control_args} 

FUNCTION 

The menu_display command displays a menu in a window. 

ARGUMENTS 

menu_name 

is the name that was assigned to the menu when it was stored. 

CONTROL ARGUMENTS 

-io_switch STR, -is STR 

specifies the name of an I/O switch for a window. The default is user_outpuL 

-pathname PATH, -pn PATH 

is the name of the value segment in which the menu has been stored. The value suffix 
is assumed. If this control argument is omitted, the user's default value segment is 
searched for the menu. 
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menu_get_choice menu_get_choice 



Name: menu_get__choice 

SYNTAX AS A COMMAND 

menu_get_choice menu_name {-control_args} 

SYNTAX AS AN ACTIVE FUNCTION 

[menu_get_choice menu_name {-control_args}] 

FUNCTION 

The menu_get_choice command, given the menu called menu_name on display in a window, 
gets a menu choice from the user and prints or returns it 

ARGUMENTS 

menu_name 

is the name that was assigned to the menu when it was stored. 

CONTROL ARGUMENTS 

-pathname PATH, -pn PATH 

is the name of the value segment in which the menu has been stored. The value suffix 
is assumed. If this control argument is omitted, the user's default value segment is 
searched for the menu. 

-io_switcb STR, -is STR 

where STR is the name of an I/O switch for a window. The default is user_i/o. 

-default_fkeys STR, -fkeys STR 

specifies the keys to be used if the terminal does not have function keys or if the 
terminal does not have the proper set of function keys. See "Notes on Function Keys" 
below. 

-function_keys STR, -fkeys STR 

specifies the keys to be used to simulate function keys. This control overrides any 
function key definitions already established for the terminal. See "Notes on Function 
Keys" below. 
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menu_get_choice menu_get_choice 



NOTES ON FUNCTION KEYS 

Many terminals have function keys. On many of these terminals (such as the Honeywell 
VIP7801) they are labelled "Fl", "F2", etc. If you type one of these function keys, 
menu_get_choice returns the string "F*'\ where * is a one or two digit number signifying 
which function key was pressed. It is possible to specify your own set of keystrokes to be 
used in lieu of the terminal's function keys, or to specify a set of keystrokes to be used if 
the terminal does not have enough function keys. These are done by using the -fkeys and 
-dfkeys control arguments. Each of these control arguments is followed by a string. Each 
character in this string is used to simulate a function key. The first character is used to 
simulate function key 0, the next to simulate function key 1, etc. To simulate a given 
function key, type esc-C, where C is the character corresponding to the function key. Thus 
if the string is "0123456789", typing esc-2 will return F2. 

The -fkeys control argument is used to specify keystrokes to be used instead of any which 
might be defined for the terminal. If this control argument is given, then the simulation of 
function keys always takes place. 

The -dfkeys control argument is used if you want to use the terminal defined function keys 
if possible, but wish to specify key sequences to be used to simulate function keys if 
necessary. Each character in the string following -dfkeys corresponds to one function key. If 
the character is a space, it means it makes no difference if the terminal has a function key 
corresponding to that position. If the character is not a space, that character will be used to 
simulate a function key if necessary. If the terminal does not have a function key for every 
non-space character in the string, then the -dfkeys string is used to simulate function keys. 
Thus, the string " A ?p q" means that you do not care whether the terminal has a function 
key or a function key 3, but you wish to use function keys 1,2, and 4. If any of these 3 
function keys is not present on the terminal, then esc-? will substitute for Fl, esc-p will 
substitute for F2, and esc-q will substitute for F4. 
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menu_list menu_list 

Name: menu__list 

SYNTAX AS A COMMAND 

menu_llst {menu_s tar name} {-contro1_arg} 

SYNTAX AS AN ACTIVE FUNCTION 

[menu_list {menu_s tar name} {-control_arg}] 

FUNCTION 

The menu_list command lists the names of the menu descriptions stored in a value segment 

ARGUMENTS 

menu_starname 

is a starname that is used to search for menu descriptions. If it is omitted, the default 
is **. 

CONTROL ARGUMENTS 

-pathname PATH, -pn PATH 

is the pathname of the value segment in which the menu has been stored. The value 
suffix is assumed. If this control argument is not given, the user's default value segment 
(udd>Project_id>Person_id>Person_id.value) is searched for the menu. 
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windowcall 



windowcall 



Name: window_call 

SYNTAX AS A COMMAND 

window_call arguments {-control_args} 

SYNTAX AS AN ACTIVE FUNCTION 

[w i ndow_ca 1 1 arguments {-control_args}] 

FUNCTION 

The window_call command provides a command interface to the video system. 

ARGUMENTS 

are listed below. A detailed description follows the control arguments section. 



bell 

change_wi ndow, chgwd 
clear_region, clrgn 
clear_to_end_of_l ine, cleol 
c 1 ear_to_end_of _w i ndow , c 1 eowd 
clear_window, clwd 
create_window, crwd 
delete_chars, dlch 
delete_window, dlwd 
get_echoed_chars, gech 
get_f i rst_l ine, gfl 
get_one_unechoed_char , gouch 
get_posi tion, gpos 



get_terminal_height, gtmhgt 

get_terminal_width, gtmwid 

get_unechoed_chars, guch 

get_wi ndow_height, gwdhgt 

insert_text, i tx 

i nvoke 

overwr i te_text, otx 

revoke 

scrol l_region, scrgn 

set_posi tion, spos 

set_posi tion_rel , sposrel 

supported_terminal 

sync 

video_invoked 

wr i te_sync_read, wsr 



CONTROL ARGUMENTS 

-column C, -col C 

specifies a column on the screen. The leftmost column is 1. If -column is not specified, 
the default is the remainder of the screen. 

-count N, -ct N 

specifies a count See the specific requests for details. 



-height NL, -hgt NL 

specifies the height of a region or a window for a request, 
the default is the remainder of the screen. 



If -height is not specified, 



5-10 



CP51-02 



window call window_call 



-iojswitch WINDOW, -is WINDOW 

" where WINDOW is an I/O switch. The operation is performed on the window associated 
with the named I/O switch. 

-line L 

specifies a line on the screen. The top line is line 1. 

-line_speed N, -Is N 

specifies the speed of the terminal's connection to Multics. N is in characters per 
second. 

-terminal_type STR, -ttp STR 

where STR is a terminal type. Information on accepted terminal types can be obtained 
with the print_terminal_types (ptt) command. 

-string TEXT, -str TEXT 

specifies a text string for display. If TEXT contains blanks or other special command 
processor characters it must be enclosed in quotes. 

-width NC, -wid NC 

specifies the width of a region for a request If -width is not specified, the default is 
the remainder of the screen. 

Argument Descriptions 



bell 

SYNTAX AS A COMMAND 

wdc bell {-io_switch WINDOW} 

FUNCTION 

activates the terminal bell. On some terminals, this may produce a visual indication instead of 
an audible tone. The cursor position must be defined. The cursor is positioned to the current 
position of the specified window, if it is elsewhere on the screen. If -io_switch is not 
specified, user_i/o is assumed. 
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window call window_call 



change window, chgwd 

SYNTAX AS A COMMAND 

wdc chgwd {-line L} {-column C} {-height NL} {-width NC} 
| {-io_switch WINDOW} 

FUNCTION 

changes the origin or size of the specified window. At least one of -line, -column, -height, 
or -width is required, -line L specifies the line number or the screen where the window is 
to begin. If -line is not supplied, the default is column 1. If only the -line control 
argument is given (changing the top line of the window), the window length is automatically 
adjusted. That is, if the -line control argument increases the value of the top line number 
(moving the window down), the window length shrinks accordingly. However, if the -line 
control argument decreases the top line number (moving the window up), the length remains 
the same, -column C specifies the column number on the screen where the window is to 
begin. If -column is not supplied, the default is column 1. If only the -column control 
argument is given (changing the first column on the left), the window width is automatically 
adjusted, -height NL specifies the height of the window. If height is not specified, the 
default is the remainder of the screen. If only the -height control argument is given 
(changing the window length), the origin line remains the same, -width NC specifies the 
width of the window. If width is not specified, the default is the remainder of the screen. 
If only the -width control argument is given (changing the window width), the origin column 
remains the same. If -io_switch is not specified, user_i/o is assumed. See Section 2 for 
more information on the use of this command. 

clear region, clrgn 

SYNTAX AS A COMMAND 
| wdc clrgn -line N -column N -height N -width N {-io_switch WINDOW} 

FUNCTION 

clears the specified rectangular region of the window to blanks. The region may be part or 
all of the window. If -io_switch is not specified, user_i/o is assumed. See Section 2 for 
more information on the use of this command. 

clear_to_end__of_line, cleol 

SYNTAX AS A COMMAND 
| wdc cleol {-io_switch WINDOW} 
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window_call window call 



FUNCTION 



clears the line from the current cursor position to the end of the line to blanks. The current 
cursor position must be defined. If -io_switch is not specified, user_i/o is assumed. 

clear to end__of_window, cleowd 

SYNTAX AS A COMMAND 

wdc cleowd {-io_switch WINDOW} 

FUNCTION 

clears the window from the current cursor position to the end of the window to blanks. The 
current cursor position must be defined. If -io_switch is not specified, user_i/o is assumed. 

clear window, clwd 

SYNTAX AS A COMMAND 

wdc clwd {-io_switch WINDOW} 

FUNCTION 

clears the specified window so that its content becomes entirely blank. The current cursor 
position is defined to be at Line 1, Column 1 of the specified window. If -io_switch is not 
specified, user_i/o is assumed. See Section 2 for more information on the use of this 
command. 

create window, crwd 

SYNTAX AS A COMMAND 

wdc crwd -io_switch WINDOW {-line L -column C -height NL -width NC} 

FUNCTION 

creates a new window on the screen with name (and I/O switch) WINDOW, -line L specifies 
the line number on the screen where the window is to begin. If -line is not supplied, the 
default is line 1. -column C specifies the column number on the screen where the window is 
to begin. If -column is not supplied, the default is column 1 -height NL specifies the height 
of the window. If -height is not specified, the default is the remainder of the screen, 
-width NC specifies the width of the window. If -width is not specified, the default is the 
remainder of the screen. The window is blank when created, and the cursor position is Line 
1, Column 1 of the new window. See Section 2 for more information on the use of this 
command. 



5-13 CP51-02 



window_call window_call 



delete chars, dlch 

SYNTAX AS A COMMAND 

| wdc dlch -count N {-io_switch WINDOW} 

FUNCTION 

deletes N characters to the right of the current cursor position on the current line. The 
cursor remains stationary; characters to the right of the deleted characters move to the left to 
fill the vacated space. The current cursor position must be defined. If -io_switch is not 
specified, user_i/o is assumed. 

delete_window, dlwd 

SYNTAX AS A COMMAND 

\ wdc dlwd -io_switch WINDOW 

FUNCTION 

destroys the specified window. The I/O switch is closed and detached. See Section. 2 for 
more information on the use of this command. 

get__echoed_chars, gech 

SYNTAX AS A COMMAND 

| wdc gech -count N {-io_switch WINDOW} 

FUNCTION 

reads characters from the terminal until either N characters or a break character is read. All 
characters except the break are echoed on the screen in the current window. For information 
on break characters, see the break_table control order in the description of window_io_ in 
Section 7. The current cursor position must be defined. If -io_switch is not specified, 
user_i/o is assumed. 
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window_call window call 



ACTIVE FUNCTION USAGE 

two strings are returned. The first contains any nonbreak characters read, and the second 
contains the break character, if any. 

get__first __line, gfl 

SYNTAX AS A COMMAND 

wdc gfl {-io_switch WINDOW} 

FUNCTION 

prints the line on the screen where the specified window begins. If -io_switch is not 
specified, user_i/o is assumed. 

ACTIVE FUNCTION USAGE 

returns the line on the screen where the specified window begins. If -io_switch is not 
specified, user_i/o is assumed. 

get_one_unechoed__char, gouch 

SYNTAX AS A COMMAND 

wdc gouch {-io_switch WINDOW} 

FUNCTION 

reads a single unechoed character from the terminal. If -io_switch is not specified, user_i/o 
is assumed. 

ACTIVE FUNCTION USAGE 

returns a single unechoed character from the terminal. 

get_position, gpos 

SYNTAX AS A COMMAND 

wdc gpos {-io_swi tch WINDOW} 

FUNCTION 

prints the current line and column position of the cursor. 
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window_call windowcall 



ACTIVE FUNCTION USAGE 

returns the line and column position as a pair of integers separated by a space. If -io_switch 
is not specified, user_i/o is assumed. 

get terminal height, gtmhgt 

SYNTAX AS A COMMAND 

wdc gtmhgt 

FUNCTION 

prints the total number of lines on the user's terminal. 

ACTIVE FUNCTION USAGE 

returns the total number of lines on the user's terminal. 

get terminal width, gtmwid 

SYNTAX AS A COMMAND 

wdc gtmwid 

FUNCTION 

prints the total number of columns on the user's terminal. 

ACTIVE FUNCTION USAGE 

returns the total number of columns on the user's terminal. 

get_unechoed chars, guch 

SYNTAX AS A COMMAND 

wdc guch -count N {-io_switch WINDOW} 

FUNCTION 

reads characters from the terminal until either N characters or a break character are read. 
The current cursor position must be defined. If -io_switch is not specified, user_i/o is 
assumed. 
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window_call window ^ 



ACTIVE FUNCTION USAGE 

returns two strings. The first contains any nonbreak characters read, and the second contains 
the break character, if any. 

get__window_Jieight, gwdhgt 

SYNTAX AS A COMMAND 

wdc gwdhgt {-io_switch WINDOW} I 

FUNCTION 

prints the height of the specified window. 

insert_text, itx 

SYNTAX AS A COMMAND 

wdc itx -string window {-io_switch WINDOW} i 

FUNCTION 

displays the text string window at the current cursor position. If there are any characters to 
tne right of the current position on the current line th*v »o mov ~A t« tv,^ ^»u» ♦_ 
accommodate the new string. There is no wraparound feature; if text goes off the screen it 
is dropped. The text string window may contain only printable ASCII characters. Use the I 
io_call put_chars command to display nonprintable characters in a readable form If 
-io_switch is not specified, user_i/o is assumed. 

invoke 

SYNTAX AS A COMMAND 

wdc invoke {-line_speed N, -Is N} 

FUNCTION 

activates the video system on the user's terminal. If no line speed is specified, the current • 
line speed is used. The user's terminal must be attached with the tty_ I/O module If I 
graphics or auditing are in use they must be removed before this command is given The 
settings of the following tty_ modes are copied when the video system is invoked: vertsp 
can, erkl, esc, red, and ctl_char. In addition, if *pl is set on video system invocation, A more 
will be set in the video system. (For more details on modes, see the window_io_ I/O 
module in Section 7.) Similarly, the settings of the current erase and kill characters are 
copied when the video system invoked. (See "Real-Time Editing" in Section 4 for details) 
See Section 2 for more information on the use of this command. 
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• a , -«ii window_call 

window_call _ 



overwrite text, otx 

SYNTAX AS A COMMAND 

wdc otx -string STR {-io_switch STR} 

FUNCTION 



displays the text string STR at the current cursor position in the window. If there is any 
text to the right of the current position in the window, it is overwritten with the supplied 
string. The text string STR may contain only printable ASCII characters. Use the 10 call 
put.chars command to display nonprintable characters in a readable form. If -io_switcn is 
not specified, user_i/o is assumed. 

revoke 

SYNTAX AS A COMMAND 

wdc revoke 

FUNCTION 

removes the video system from the user's terminal. The standard tty_ attachment is restored. 
The settings of the following modes are copied when the video system is revoked: vertsp 
can erkl, esc, red, and ctl_char. If A more is set while in the video system, *pl mode will 
be 'set after revoking the video system. (For more details on modes, see the window jo_ I/O 
module in Section 7.) Similarly, the settings of the current erase and kill characters are 
copied when the video system is revoked. (See "Real-Time Editing" in Section 4 for details.) 
See Section 2 for more information on the use of this command. 

scroll region, scrgn 

SYNTAX AS A COMMAND 
| wdc scrgn -count N {-line L -height C -io_switch WINDOW} 

FUNCTION 

scrolls the specified region N lines as specified by -count The specified region is the whole 
width of the screen. It can be a whole window or part of a window. If -count N is 
negative the window is scrolled down, and if it is positive the window is scrolled up. If lines 
are scrolled off the screen they are dropped. If -line is not supplied, the default is 1. If 
-height is not supplied, the remainder of the window is scrolled. If -io_switch is not 
specified, user_i/o is assumed. 
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window_call window call 



set position? spos 

SYNTAX AS A COMMAND 

wdc spos -line L -column C {-io_switch WINDOW} 

FUNCTION 

positions the cursor to the specified line and column of the specific window. If -io_switch is 
not specified, user_i/o is assumed. 

set_position rel, sposrel 

SYNTAX AS A COMMAND 

wdc sposrel -line L -column C {-io_switch WINDOW} 

FUNCTION 

changes the cursor position by N lines and N columns. If -io_switch is not specified, 
user_i/o is assumed. The current cursor position must be defined. One of the control_args 
must be specified and both may be specified. Whichever control_arg is not specified defaults 
to zero. 

supported terminal 

SYNTAX AS A COMMAND 

wdc supported_terminal {-ttp terminal_type} 

FUNCTION 

returns "true" if the video system can be invoked on the specified terminal type. If no 
terminal type is specified, the current terminal type is used. 

sync 

SYNTAX AS A COMMAND 

wdc sync {-io_switch WINDOW} 

FUNCTION 

waits for the last operation performed on the window to be completed. Over certain 
networks it may not be possible to actually wait for delivery of the characters to the 
terminals. If -io_switch is not specified, user_i/o is assumed. 

5-19 CP51-02 



window call window_call 



video_invoked 

SYNTAX AS A COMMAND 

wdc video_ invoked 

FUNCTION 

returns "true" if the video system is in use in the user's process. 

write sync_read, wsr 

SYNTAX AS A COMMAND 

wdc wsr -string STR -count N {-io_switch WINDOW} 

FUNCTION 

displays a prompting string STR at the current cursor position in the window, and then reads 
input typed in response to the prompt Characters are read unechoed, until either N 
characters or a break character is read. If -io_switch is not specified, user_i/o is assumed. 

ACTIVE FUNCTION USAGE 

prints a prompting string and returns the characters read. 
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SECTION 6 
PL/I SUBROUTINE INTERFACE 



This section contains descriptions of the PL/I subroutines used by the menu and video 
software, presented in alphabetical order. 
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Name: menu 



menu_ 



The menu_ subroutine provides menu display and selection services. It can display a menu in 
a window and get a selection from the user. The entries work with menu objects. A menu 
object is a pointer to an internal description of a menu. The caller is expected to preserve 
the pointer, and to perform no operation on it other than comparison with the null pointer 
or with another menu object, except through the menu_ subroutine. Declarations for the 
entries and the associated structures are in the include file menu_dcls.incl.pll described below 
in "Data Structures". 

Entry: menu Screate 

This entry creates a menu object given its description. The menu data structure is allocated 
in a caller supplied area, and may be saved across processes by calling menu_$store. A 
pointer to the new menu is returned, also with the minimum size of a window to hold the 
menu. 

USAGE 

declare menu_$create entry ((*) char (*) varying, (*) char (*) varying, 
(*) char (*) varying, ptr, (*) char (1) unal , ptr, ptr, ptr, 
fixed bin (35)) ; 

call menu_$create (choices, headers, trailers, format_ptr, keys, area_ptr, 
needs_ptr, menu, code); 

ARGUMENTS 

choices . . . . 

is an array of the names of the options. (Input)" If the maximum number of choices is 
exceeded, the code menu_et_$too_many_options is returned. The current maximum is 61. 

headers , . . 

is an array of headers. (Input) If the length of the first header is zero, then no headers 
are used. This allows the caller to specify no headers, without resorting to a zero-extent 
array, which is invalid PL/ 1. 

trailers ., . t 

is an array of trailers. (Input) As for headers, a zero-length first trailer means that no 

trailers are displayed. 

format_ptr r ^ , T . _ . 

points to a structure, menu_format, that controls formatting of the menu. (Input) This 
structure is described below in "Data Structures". 
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keys 

is an array specifying the keystroke for each option, (Input) The array must have at 
least as many elements as the array of option names. If not, the error code 
menu_et_$too_few_keys is returned. It may have more keys than choices. Each item of 
the array must be unique, or menu_et_$keys_not_unique is returned. If the valid keys 
(the keys for which there are choices) are either all upper case or all lower case, 
menu_$get_choice will treat upper and lower case letters identically. 

area_ptr 

is a pointer to an area where the menu description is allocated. (Input) If the area is 
not large enough, the area condition is signalled. If this pointer is null, the system free 
area is used. 

needs_ptr 

points to the menu_requirements structure giving requirements to display the menu. 
(Input) The structure is described below in "Data Structures". The caller supplies this 
structure and fills in the version number menu_requirements_version_l, the remaining 
members are output from this entry. 

menu 

is a newly created menu object (Output) 

code 

is a standard system error code, or an error code from menu_et_. (Output) 

Entry: menu (delete 

This entry deletes a menu object from a specified value segment 

USAGE 

declare menu_$delete entry (char (*) , char (*) , char (*) , fixed bin (35)); 

call menu_$delete (dirname, entryname, menu_name, code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the segment (Input) It must have the value suffix. 

menu_name 

is the name that was assigned to the menu when it was stored (see the description of 
menu_$store). (Input) 

code 

is a standard system error code. (Output) 
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Entry: menu_$describe 

This entry fills in a caller-supplied data structure describing some of the aspects of a menu 
object The caller can use this to ensure a window is sufficiently large to hold a menu. 

USAGE 

declare menu_$descr ibe entry (ptr, ptr, fixed bin (35)); 

call menu_$descr ibe (menu, needs_ptr, code); 

ARGUMENTS 

menu 

is the menu object to describe. (Input) 

needs_ptr 

points to a structure declared like menu_requirements described in "Data Structures" 
below. (Input) The caller fills in the version to be menu_requirements_version_l, and the 
remaining members are filled in by this entry. 

code 

is a standard system error code. (Output) 

Entry: menu (destroy 

This entry is used to delete a menu object The caller uses this to free storage of a menu, 
since the representation of a menu is not known outside the menu_ subroutine. This entry 
has no effect on screen contents or on stored menus. 

USAGE 

declare menu_$ destroy entry (ptr, fixed bin (35)); 

cal 1 menu_$destroy (menu, code) ; 

ARGUMENTS 

menu 

is the menu object to destroy. (Input) 

code 

is a standard system error code. (Output) 
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Entry: menu_$display 

This entry displays a menu object on a supplied window. 

USAGE 

declare menu_$di splay entry (ptr, ptr, fixed bin (35)); 

call menu_$display (window, menu, code); 

ARGUMENTS 

window 

is a pointer to an IOCB for an I/O switch attached through window_io_. (Input) This 
window must be large enough to hold the menu. A menu window should be used ONLY 
for menu I/O, if redisplay optimizations are desired. 

menu 

is the menu object to be displayed. (Input) 

code 

is a standard system error code. (Output) 

Entry: menu_$get choice 

This entry returns a choice from a menu. The menu is assumed to be already displayed in 
the window. 

USAGE 

declare menu_$get_choice entry (ptr, ptr, ptr, bit (1) aligned, fixed bin, 
fixed bin (35)); 

call menu_$get_choice (window, menu, function_key_info, fkey, selection, 
code) ; 

ARGUMENTS 

window 

is a pointer to the IOCB for the I/O switch used to display the menu. (Input) 

menu 

is the menu object on display in the window. (Input) 

function_key_info 

is a pointer to a data structure describing the function keys available on the terminal. 
(Input) This data structure is obtained by the caller from the ttt_info_$function_key_data 
subroutine. If this pointer is null, no function keys are used. 
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fkey 

returns a value of Tb if a function key was hit instead of a menu selection. (Output) 

selection 

gives the option number or function key number chosen by the user. For an option, it 
is a number between 1 and the highest defined option, inclusive. For a function key, it 
is the number of the function key. 

code 

is a standard system error code. (Output) 

NOTES 

If a terminal has no function keys, the caller can define input escape sequences for function 
keys. These may be chosen to have mnemonic value to the end user. For example, if 
Function Key 1 is used to print a help file, the input sequence ESC h could replace it In 
some applications, this will be easier for the end user to remember than an unlabelled 
function key. The caller can define these keys by allocating and filling in the same function 
key structure normally returned by the ttt_info_ subroutine. 

If a key is hit that is not one of the option keys and is not a function key, then the 
terminal bell is rung. 

Entry: menu^_$list 

This entry lists the menu objects stored in a specified value segment 
USAGE 

declare menu_$ list entry (char (*) , char (*) , char (*) , ptr, fixed bin, ptr, 
fixed bin (35)) ; 

call menu_$list (dirname, entryname, menu_starname, area_ptr, 
menu_1 ist_info_yersion, menu_1 ist_info_ptr, code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the segment (Input) It must have the value suffix. 

menu_starname 

is matched against the names of the menus stored in the segment. (Input) Only names 
that match menu_starname are returned, (see the description of menu_$store). 

area_ptr 

is a pointer to an area in which to allocate the structure containing the menu names. 
(Input) If it is null, the system free area is used. 
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menu_list_info_version 

is the version of the menu_Iist_info structure that the caller expects. (Input) It must be 
a supported menu_Iist_info structure version. The only supported version is 
menu_list_info_version_l. 

menu_list_info_ptr 

is a pointer to the menu_list_info structure, described below under "Data Structures". 
(Output) 

code 

is a standard system error code. (Output) 

Entry: menu $retrieve 

This entry retrieves a menu from a specified segment The segment must be a value segment 
The menu data structure is allocated in a caller-supplied area. The menu information is 
copied from the menu object stored in the segment into the newly allocated structure. 

USAGE 

declare menu_$retr ieve entry (char (*) , char (*) , char (*) , ptr, ptr, 
fixed bin (35)) ; 

call menu_$ retrieve (dirname, entryname, menu_name, area_ptr, menu_ptr, code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the segment (Input) It must have the value suffix. 

menu_name 

is the name that was assigned to the menu when it was stored (see the description of 
menu_$store). (Input) 

area_ptr 

is a pointer to an area where the menu object is allocated. (Input) If this argument is 
null, the system free area is used. If the area is not large enough, the area condition is 
signalled. 

menu_ptr 

is a pointer to the menu object that is retrieved from the segment (Output) 

code 

is a standard system error code. (Output) 
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Entry: menu $store 

This entry stores a menu object in a specified segment The specified segment must be a 
value segment. 

USAGE 

declare menu_$store entry (char (*) , char (*) , char (*) , bit(l) aligned, ptr, 
fixed bin (35)); 

call menu_$store (dirname, entryname, menu_name, create_sw, menu_ptr, code); 
ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the segment. (Input) It must have the value suffix. 

menu_name 

is a name to be assigned to the menu. (Input) 

create_sw 

determines whether or not the segment is created if it does not already exist If the 
segment does not exist a value of "l"b will cause it to be created. (Input) 

menu_ptr 

is a pointer to the menu object that is to be stored in the segment (Input) 

code 

is a standard system error code. (Output) 

DATA STRUCTURES 

A menu is described by the "menu_format" structure. It is declared in menu_dcls.incl.pll. 

del 1 menu_format aligned based (menu_format_ptr) , 

2 version fixed bin, 
2 constraints, 

3 max_width fixed bin, 

3 max_height fixed bin, 

2 n_columns fixed bin, 
2 flags, 

3 center_headers bit (1) unal, 

3 center_trai lers bit (1) unal, 

3 pad bit (3 1 *) unal, 

2 pad_char char (1) ; 
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STRUCTURE ELEMENTS 



menu_format 

specifies the format for menu display. (Input) It gives limits for number of lines and 
characters per line, specifies the number of columns (of options), and controls centering 
of headers and trailers. 

version 

must be menu_format_version_l. (Input) 

max_width 

is the width of the window the menu will be displayed on. (Input) This value is used 
for centering headers and aligning columns. 

max_height 

is the maximum height of the window, in lines. (Input) 

n_columns 

is the number of columns to use in displaying options. (Input) 

center_headers 

if set, header lines will be centered using the window width supplied above. (Input) If 
not set, they are flush with the left edge of the window. 

center_trailers 

same as center_headers, but for trailers. (Input) 

pad 

must be "0"b. (Input) 

pad_char 

is the character used for centering headers and/or trailers. (Input) 

THE MENUJ.ISTJNFO STRUCTURE 

This entry returns information in the menu_list_info structure, found in the include file 
menu_list_info.incl.pll, shown below: 

del 1 menu_l ?st_info aligned based (menu_l ist_info_ptr) , 
2 version fixed bin, 

2 n_names fixed bin, 

2 name_string_ length fixed bin (21), 
2 names (menu_l ist_n_names refer 

(menu_l i st_i nfo.n_names) ) al igned, 
3 position fixed bin (21), 

3 length fixed bin (21) , 

2 name_string character (menu_l ist_name_str ing_length 

refer (menu_l ist_info.name_str ing_length) ) 
unal igned; 
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STRUCTURE ELEMENTS 



version 

is the version of this structure, menu_list_info_version_l. (Output) 

n_names 

is the number of menu object names that matched the supplied starname. (Output) 

name_string_length 

is the total length of all the names that matched the supplied starname, concatenated 
together. (Output) 

names 

is an array of information with one entry for each name that matched the specified 
starname. (Output) 

position 

is the position in the string menu_list_info.name_string of this menu name. (Output) 

length 

is the length of this menu name in the string menu_list_info.name_string. (Output) 

name_string 

contains all the returned names, concatenated together. (Output) The PL/I "defined" 
attribute can be used to advantage to refer to individual names. For example, we wish to 
print the menu name indexed by name_index. 

beg i n ; 
declare this_name character (menu_l Fst_info. length (name_ index) ) 
defined (menu_l ist_info.name_str i ng) 
position (menu_l ist_i nf o. posit ion (name_index) ) ; 

call ioa_ ("The ~d'th menu name is: ""a", name_index, this_name); 
end; 
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THE MENU REQUIREMENTS STRUCTURE 

The requirements for a menu are specified by the menu_requirements structure. It is declared 
in menu_dcls.incl.pll. 

del 1 menu_requirements aligned based (menu_requi rements_ptr) , 

2 version fixed bin, 

2 lines_needed fixed bin, 

2 width_needed fixed bin, 

2 n_options fixed bin; 

STRUCTURE ELEMENTS 



version 

is set by the caller, and must be menu_requirements_version_l. (Input) 

lines_needed 

is the number of lines required. (Output) If the window does not have this number of 
lines, menu display will fail. 

width_needed 

is the number of columns needed. (Output) 

n_options 

is the number of options defined. (Output) 

The include file, menu_dcls.incl.pll, also provides an array of key characters that may be 
used in the menu to select options. This array can be used by the caller as input to the 
menu_$create entry. Its name is MENU_OPTION_KEYS. 
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Name: video data 

The video_data_ subroutine is a data segment containing information about the video system. 

Entry: video data_$terminal iocb 

This is the terminal control switch IOCB pointer. If the video system is activated for the 
user's terminal, this pointer is nonnull, and points to the IOCB for the switch user_terminal_. 

USAGE 

fnt typ declare video_data_$terminal_iocb pointer external static; 

NOTES 

User programs may use this pointer for two purposes: 

1. Inquiring as to whether the video system is activated, by checking to see if the pointer 
is null. 

2. Determining the physical characteristics and capabilities of the terminal. This may be 
accomplished with the get_capabilities control order, described under the window_io_ I/O 
module. The height and width returned will be that of the physical terminal screen. 

No other manipulations of this switch are permitted. 
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Name: video_utils_ 

This subroutine provides interfaces for activating and de-activating the video system. 

Entry: video utils Sturn, on login_channel 

This entry removes the existing attachment of the user's terminal, replacing it with the video 
system. When this entry returns successfully, the switch user_terminal_ is attached through 
tc_io_ to the user's terminal. The switch user_ i/o is attached through window_io_ to a 
window covering the entire screen, invoked: vertsp, can, erkl, esc, red, and ctl_char. In 
addition, if A pl is set on video system invocation, A more will be set in the video system. 
(For more details on modes, see the window_io_ I/O module.) Similarly, the settings of the 
current erase and kill characters are copied when the video system is invoked. (See 
"Real-Time Editing" for details.) To see how the standard I/O switch attachments change 
when you activate the video system on your terminal, refer to Figure A-2 in Appendix A. 

USAGE 

declare video_uti ls_$turn_on_login_channel entry (fixed bin (35) # char (*) ) ; 

call video_uti ls_$turn_on_login_channel (code, reason); 

ARGUMENTS 

code 

is a standard system error code. (Output) 



reason 

contains information about the error, if there is one. (Output) (128 characters are enough 
to hold any message that may be returned in reason.) 

NOTES 

If the video system is already in service on the user's terminal, the status code 
video_et_$wsys_invoked is returned, and the value of reason is not defined. 

If the activation of the video system fails, the original attachment of the terminal (through 
tty_) is restored, and information is returned in reason and code. 

In particular, if the switch user_i/o is not currently attached through tty_, the code 
video_et_$switch_not_attached_with_tty_ is returned. This may indicate that the user has 

h*«*l i>lAlg, Wl UIW £l O-fJlllW •> j S> twill 111 ^lUVVi X 11W UlvOjUgV 1 W I»U1 UVU 111 1 WClt9\Sll <XVL v idw uiv udwi IAJ> 

remove graphics or auditing and try again. 
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Entry: video_utils $turn off__login_channel 

This entry reverses the actions of video_utils_$turn_on_login_channel. That is, it removes the 
window attachment of user_i/o, detaches terminal control from the user's terminal, and 
attaches user_i/o to the user's terminal via tty_. The settings of the following modes are 
copied when when the video system is revoked: vertsp, can, erkl, esc, red, and ctl_char. If 
A more is set while in the video system, A pl mode will be set after revoking the video system. 
(For more details on modes, see the window_io_ I/O module.) Similarly, the settings of the 
current erase and kill characters are copied when the video system is revoked. (See 
"Real-Time Editing" for details.) It is the user's responsibility to detach any windows other 
than user_io before calling this entry point 

USAGE 

declare video_uti ls_$turn_of f_login_channel entry (fixed bin (35)); 

call video_uti ls_$turn_of f_login_channel (code); 

ARGUMENTS 

code 

is a standard system error code. (Output) It is nonzero if and only if the video system 
can not be removed from the user's terminal. 



6-14 CP51-02 



window_ window 



Name: window 

The window_ subroutine provides a terminal independent interface to video terminal 
operations. More specifically, it controls and performs I/O to a window. 

The window_ subroutine is used in conjunction with the iox_ subroutine call entry points in 
the window_io_ I/O module. The window_ and video_utils_ subroutines together perform the 
same functions as the window_call command. 

The virtual terminal implemented by window_ corresponds closely to common video terminals. 
The features of the terminal are defined implicitly by the entries below. Not all entries can 
be supported on all terminals. The result of calling an unsupported feature is the error code 
video_et_$capability_lacking. Programs can determine whether the device in question supports 
a given operation by using a get_capabilities control order, described under the window_io_ 
I/O module. 

Additional terminals may be supported by defining their video attributes in the Terminal Type 
File (TTF). The TTF is described in the Multics Programmer's Reference Manual Order 
No. AG91. 

Some entry points require that the current cursor position be defined when they are called. 
The current position is defined unless a call is made to the write_raw_text entry point, or an 
asynchronous event changes the window contents. If the current position is not defined, these 
entry points will return the status code video_et_$cursor_position_undefined. 

If an asynchronous event changes the state of the window, status will be set for the window. 
Once window status is set, all calls to window_ on that window will return the status code 
video_et_$window_status_pending until a get_window_status control order is used to pick up 
the status. 

The calling sequences for all the entry points are in the include file window_dcls.incl.pll. 

Entry: window $bell 

This entry activates the terminal alarm. For most terminals, this will be the audible bell. For 
some it will be a visible signal. 

USAGE 

declare wi.ndow_$bel 1 entry (ptr, fixed bin (35)); 

call window_$be1) (iocb_ptr, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
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NOTES 

The current cursor position must be dfined for this call. If the cursor is in some other 
window on the screen when this call is made, it is moved to the current position in this 
window. 

Entry: window $change_column 

This entry moves the cursor to a different column on the current line, without changing the 
line. 

USAGE 

declare window_$change_column entry (ptr, fixed bin, fixed bin (35)); 

call window_$change_column (iocb_ptr, new_co 1 umn , code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

new_column 

is the new column. (Input) 

code 

is a standard system error code. (Output) 

NOTES 

The current cursor position must be defined. 

Entry: window Schange line 

This entry moves the cursor to a new line without changing the column. 

USAGE 

declare window_$change_l ine entry (ptr, fixed bin, fixed bin (35)); 

call window_$change_l ine (iocb_ptr, new_line, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

new_line 

is the new line. (Input) 
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code 

is a standard system error code. (Output) 

Entry: window Sclear region 

This entry replaces the contents of the region specified with spaces, and leaves the cursor at 
the upper left-hand corner of the region. The region is defined by giving the upper 
left-hand corner (line and column), and the width and height of the region. 

USAGE 

declare window_$clear_region entry (ptr, fixed bin, fixed bin, fixed bin, 
fixed bin, fixed bin (35)); 

call window_$clear_region (iocb_ptr, start_line, start_col, n_lines, n_cols, 
code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

startjine 

is the number of the line where clearing will begin. (Input) 

start_col 

is the number of the column where clearing will begin. (In«ut) 

n_lines 

is the number of lines which will be cleared. (Input) 

n_cols 

is the number of columns which will be cleared. (Input) 

code 

is a standard system error code. (Output) 

NOTES 

The rectangular region described in cleared. The cursor position defined at (start_line, 
start_col). 
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Entry: window Sclcar to end__of__line 

This entry clears everything to the right of the cursor on the current line to spaces. Positions 
to the left of the cursor are not affected. The cursor is not moved. 

USAGE 

declare window_$clear_to_end_of_l ine entry (ptr, fixed bin (35)); 

call window_$clear_to_end_of_l ine (iocb_ptr, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 

NOTES 

The cursor position must be defined. 

Entry: window_$clear_to_end of_window 

This entry clears all of the window between the cursor and the end of the window. This 
includes everything to the right of the cursor on the current line, and all lines below the 
cursor. The cursor is not moved. 

USAGE 

declare window_$clear_to_end_of_window entry (ptr, fixed bin (35)); 

call window_$clear_to_end_of_window (iocb_ptr, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 

NOTES 

The current cursor position must be defined. 
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Entry: window $clear window 

This entry clears the entire window to spaces, and leaves the cursor at home. 

USAGE 

declare window_$clear_window entry (ptr, fixed bin (35)); 

call window_$clear_window (iocb_ptr, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 

NOTES 

The cursor position is defined to be at line 1, column 1 after the screen is cleared. 

Entry: window_$create 

This entry creates a new window on the terminal screen. 

USAGE 

declare window_$ create entry (ptr, ptr, ptr, fixed bin (35)); 

call window_$create (terminal_iocb_ptr , window_info_ptr , window_iocb_ptr , 
code) ; 

ARGUMENTS 

terminal_iocb_ptr 

is a pointer to an IOCB for the terminal control switch. (Input) Normally this should be 
video_data_$terminal_iocb. 

window_info_ptr 

is a pointer to a standard window_position_info structure, as declared in 
window_control_info.incl.pll. (Input) 

window_iocb_ptr 

is a pointer to a detached IOCB pointer. (Input) It may be obtained with iox_$find_iocb 
which must be done before the call to window_$create. For example: 

call iox_$f ind_iocb (" top_w i ndow" , window_iocb_ptr , code); 
where the value returned for window_iocb_ptr is used in the call to window_$create. 
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code 

is a standard system error code. (Output) 

NOTES 

The window_info_ptr must point to a window_position_info structure, as declared in 
window_control_info.incl.pll. If window_position_info. width is set to zero, the window will 
occupy the full width of the screen. Currently windows must occupy the full width of the 
screen. If tc_io_.*.*in window_position_info.height is set to zero, the remainder of the screen 
is used. The iocb_ptr is an input argument, iox_$find_iocb may be used to obtain an 
iocb_ptr for a new switch. 

Entry: window Sdelete chars 

This entry deletes characters on the current line. Characters to the right of the cursor are 
moved to the left. Character positions opened up on the right margin are filled with spaces. 
It is an error to call this entry point if the terminal does not support the delete chars 
operation. 

USAGE 

declare window_$delete_chars entry (ptr, fixed bin, fixed bin (35)); 

call window_$delete_chars (iocb_ptr, n_chars, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

n_chars 

is the number of characters (starting at the current cursor position) that will be removed 
from the screen. (Input) If n_chars is zero, no action is taken. 

code 

is a standard system error code. (Output) 

NOTES 

The current cursor position must be defined. The number of characters specified by n_chars 
are deleted, and the remaining characters on the line, if any, move leftward to occupy the 
space. 
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Entry: window_$destroy 

This entry destroys an existing window, leaving its IOCB in a detached state. 

USAGE 

declare window_$destroy entry (ptr, fixed bin (35)); 

call window_$destroy (window_iocb_ptr, code); 

ARGUMENTS 

window_iocb_ptr 

is a pointer to an IOCB attached with window_$create. (Input) 

code 

is a standard system error code. (Output) 

Entry: window_$edit_line 

This entry allows applications to preload the video editor input buffer with a string. 
USAGE 

declare window_$edit_l ine entry (pointer, pointer, pointer, fixed bin (21), 
fixed bin (21), fixed bin (35)); 

call window_$edi t_l ine (iocb_ptr, window_edi t_l ine_info_ptr , buffer_ptr, 
buffer_len, n_returned, code); 

ARGUMENTS 

window_iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io. (Input) 

window_edit_line_info_ptr 

is a pointer to a window_edit_line_info structure, as declared in window_control_info.incl.pll 
(described below). (Input) 

version 

is the version number of the structure. (Input) This is currently window„editJine_version_l. 

line_ptr 

is a pointer to the initial text string to be loaded into the input buffer before editing 
begins. (Input) 

linejength 

is the length of the string pointed to by line_ptr. (Input) 
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buffer_ptr 

is a pointer to a buffer where the users input will be put (Input) 

buffer_len 

is the size of the input buffer. (Input) 

n_returned 

is the number of characters in the final output line. (Output) 

code 

is a standard system error code. (Output) 

Entry: window $get cursor position 

This entry is used to return the current position of the cursor. If the last operation done to 
the terminal was in some other window, this will not be the actual position of the cursor on 

the screen. 

USAGE 

declare window_ $get_cursor_posi tion entry (ptr, fixed bin, fixed bin, fixed 
bin (35)); 

call window_$get_cursor_posi tion (iocb_ptr, line, col, code); 
ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

line 

is the line number. (Output) 

col 

is the column position. (Output) 

code 

is a standard system error code. (Output) 

NOTES 

The current cursor position must be defined. 
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Entry: window $get_echoed_chars 

This entry accepts input from the typist, echoing the characters as typed, until either a 
specified number of characters are read, or a break character is encountered. By default, the 
break characters are the control characters plus DEL (177 octal). 

USAGE 

declare window_$get_echoed_chars entry (ptr, fixed bin (21), char {*) , fixed 
bin (21), char (1) varying, fixed bin (35)); 

call window_$get_echoed_chars (iocb_ptr, n_to_get, buffer, n_got, break, 
code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

n_to_get 

is the number of columns (N) between the cursor and the end of the line. (Input) At 
most N characters will be returned. 

buffer 

is the caller-supplied buffer that holds characters returned. (Input) 

n_got 

is the number of characters returned. (Output) Each character is echoed, 

break 

is the character that causes the echoing to stop. (Output) This character is not echoed. 

code 

is a standard system error code. (Output) 

NOTES 

This entry point returns no more than n_to_get characters in buffer. It reads and echoes 
characters until either (1) it has read n_to_get characters, or (2) it has read a break 
character. If it stops due to a break character, the break character is returned in break, 
otherwise break is equal to "". 
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Entry: window $get_one__unechoed_char 

This entry reads a single character, unechoed, from the terminal. Optionally, it can return 
instead of waiting if there are no characters available. 

USAGE 

declare window_$get_one_unechoed_char entry (ptr, char (1) varying, bit (1) 
aligned, fixed bin (35)); 

call window_$get_one_unechoed_char (iocb_ptr, char_read, block_flag, code); 
ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

char_read 

is the read character. (Output) If block_flag is "0"b, and no input is typed ahead, then 
this will be a zero length character string. 

block_flag 

if this flag is "l"b, input from the terminal is awaited if none is available. (Input) If it 
is "0"b, and no input is available, then this entry returns immediately, and sets char_read 
to "". 

code 

is a standard system error code. (Output) 

NOTES 

Beware of the PL/ 1 language definition of character string comparisons when using this entry 
with a block flag of "0"b. In PL/ 1, both of the following comparisons are true: 

(" " = " ") 
("" = " ") 

That is, a zero length varying string compares equally to a single space. To test if char_read 
is nonempty, use an expression like: 

(length (char_read) > 0) 
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Entry: window_$get__unechoed__chars 

This entry accepts input from the typist, leaving it unechoed, until either a specified number 
of characters are read, or a break character is encountered. 

USAGE 

declare window_$get_unechoed_chars entry (ptr, fixed bin (21), char (*) , fixed 
bin (21), char (1) varying, fixed bin (35)); 

call window_$get_unechoed_chars (iocb_ptr, n_to_get, buffer, n_got, break, 
code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

n_to_get 

is the number of columns (N) between the cursor and the end of the line. (Input) At 
most N characters will be returned. 

buffer 

is the caller-supplied buffer that holds characters returned. (Input) 

n_got 

is the number of characters returned. (Output) Each character is echoed. 

break 

is the character that causes the echoing to stop. (Output) This character is not echoed. 

code 

is a standard system error code. (Output) 

NOTES 

This entry point will read no more than n_to_get characters from the terminal, without 
echoing them to the typist The characters are returned in the buffer. Characters are read 
until either (1) n_to_get characters are read, or (2) a break character is read. If reading 
stops due to a break character, then the break character is returned in break. Otherwise 
break is "". 
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Entry: window {insert text 

This entry inserts text at the current cursor position: Text at the cursor or to the right of 
the cursor is shifted to the right, to accommodate the new text. It is an error to call this 
entry if the terminal does not support the insertion of text 

USAGE 

declare window_$i riser t_text entry (ptr, char (*) , fixed bin (35)); 

call window_$insert_text (iocb_ptr, text, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

text 

is the character string to be written. (Input) When converted to output, each character in 
this string must occupy exactly one print position. The length of this string must be such 
that characters moved to the right will remain on the current line in the window. If 
these conditions are not met, the result is undefined. The cursor is left after the last 
character inserted. 

code 

is a standard system error code. (Output) 

NOTES 

The current cursor position must be defined. The string "text" must contain only printable 
ASCII graphics. If it contains any other characters, the status code video_et_$string_not_printable 
is returned. 

Entry: window {overwrite text 

This entry writes text on the window in the current cursor location. If there is any text at 
or to the right of the current cursor position in the window, it is overwritten with the 
supplied string. 

USAGE 

declare window_$overwrite_text entry (ptr, char (*) , fixed bin (35)); 

call window_$overwr i te_text (iocb_ptr, text, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
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text 

is the character string to be written. (Input) This string should consist of only printable 
ASCII graphics (octal codes 040 through 176 inclusive), and may not be longer than the 
space remaining on the current line. 

code 

is a standard system error code. (Output) 

NOTES 

The cursor position must be defined. The string "text" may contain only printable ASCII 
graphics. If it contains anything else the status code video_et_$string_not_printable is 
returned. 

Entry: window_$position cursor 

This entry moves the cursor to any requested position in the window. It defines the current 
cursor position if it is undefined. 

USAGE 

declare window_$posi tion_cursor entry (ptr, fixed bin, fixed bin, 
fixed bin (35)) ; 

call window_$position_cursor (iocb_ptr, line, col, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) line is the line 
number. (Input) 

col 

is the column position. (Input) 

code 

is a standard system error code. (Output) 

Entry: window_$position_cursor_rel 

The entry moves the cursor relative to the current location. 
USAGE 

declare window_$posi tion_cursor_rel entry (ptr, fixed bin, fixed bin, 
fixed bin (35)) ; 

call window_$position_cursor_rel (iocb_ptr, line_inc, col_inc, code); 
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ARGUMENTS 

iocb_ptr 

is a pointeT to an IOCB for a switch attached with window_io_. (Input) 

line_inc 

is the change in line number. (Input) If line_inc is a positive number, the cursor is 
moved down. If it is a negative number, the cursor is moved up. If it is zero, the 
cursor's line number is not changed. 

col_inc 

is the change in column position. (Input) If col_inc is a positive number, the cursor is 
moved to the right. If it is a negative number, the cursor is moved to the left If it is 
zero, the cursor's column position is not changed. 

code 

is a standard system error code. (Output) 

Entry: window $scroll„region 

This entry scrolls a region up or down a given number of lines. A positive scroll count 
scrolls the window up, deleting lines from the top of the window and adding new blank lines 
to the bottom. The cursor's new position is at the beginning of the first new blank line. A 
negative count scrolls the window down, deleting lines from the bottom and adding lines to 
the top. The cursor is left at home. If this entry is called and the terminal does not 
support either scrolling or insert and delete lines, the result is an error status, 
video_et_$capabilities_lacking. 

USAGE 

declare window_$scrol l_region entry (ptr, fixed bin, fixed bin, fixed bin, 
fixed bin (35)) ; 

call window_$scrol l_region (iocb_ptr, start_line, n_lines, scrol l_distance, 
code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

start_line 

is the number of the first line of the region. (Input) 

n_lines 

is the number of lines that compose the region. (Input) 

scroll_distance 

is the distance in lines by which the region will be scrolled. (Input) 
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code 

is a standard system error code. (Output) 

NOTES 

The cursor position is defined to be column one on firstjine. The region from first_line for 
n_lines is scrolled scroll_distance lines, which may be negative 

Entry: window $sync 

This entry synchronizes the process with the typist by writing any pending output to the 
terminal. 

USAGE 

declare window_$sync entry (ptr, fixed bin (35)); 

call window_$sync (iocb_ptr, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 

NOTES 

The calling process is made to wait until the typist types something after the last text output 
has been transmitted to the terminal. 

Entry: window_$write_raw_text 

This entry is used to output a terminal dependent sequence. The current cursor position 
becomes undefined after this call is made. This entry should not be used to output sequences 
that put graphics onto the terminal screen, as the video system's internal screen image will 
become inconsistent This entry is used for terminal-specific features that cannot be accessed 
via the video system. 

UOHUC 

declare window_$write_raw_text entry (ptr, char (*) , fixed bin (35)); 
call window_$write_raw_text (iocb_ptr, text, code); 
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ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

text 

is any string of printable ASCII characters to be transmitted to the terminal. (Input) 

code 

is a standard system error code. (Output) 

NOTES 

Any call to window_$write_raw_text causes the cursor position to become undefined and sets 
the screen_invalid window status flag. Subsequent calls to write_raw_text will ignore this flag, 
but all other window_ entrypoints will return the status code video_et_$window_status_pending 
until the status flag is cleared. It is the responsibility of the application performing the raw 
output call to perform a get_window_status control order to clear the status flag. 

Entry: window $write sync read 

This entry writes a prompt, synchronizes input to the output of the prompt, and reads a 
response. This entry is useful for queries where it is important to avoid interpreting 
type-ahead as a response to a question. 

USAGE 

declare window_$wr i te_sync_read entry (ptr, char (*) , fixed bin (21), 
char (*) , fixed bin (21), char (1) varying, fixed bin (35)); 

call wi ndow_$wr i te_sync_read (iocb_ptr, prompt, n_to_get, buffer, n_got, 
break, code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

prompt 

is a string of printable ASCII characters which must fit on the current line. (Input) 

n_to_get 

is the number of columns (N) between the cursor and the end of the line. (Input) At 
most N characters will be returned. 
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buffer 

is the caller-supplied buffer that holds characters returned. (Input) 

n_got 

is the number of characters returned. (Output) Each character is echoed. 

break 

is the character that causes the echoing to stop. (Output) This character is not echoed. 

code 

is a standard system error code. (Output) 

NOTES 

The current cursor position must be defined. This entry overwrites the text string "prompt" 
at the current cursor position. It then reads characters typed after the prompt has been 
transmitted to the terminal. The characters are read in the same fashion as the 
get_unechoed_chars entry point. Any characters read before the prompt is transmitted, are 
buffered and returned to get_echoed_chars or subsequent get_unechoed_chars calls. 
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This section contains descriptions of the I/O modules used by the menu and video 
software, presented in alphabetical order. For details on I/O processing, see the Multics | 
Programmer's Reference Manual, Order No. AG91. | 
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Name: tc_io_ 

The tc_io_ I/O module supports terminal independent I/O to the screen of a video terminal. 

Entry points in this module are not called directly by users; rather, the module is accessed 
through the I/O system interfaces iox_. 

ATTACH DESCRIPTION 

tc_io_ {device} {-control_args} 

ARGUMENTS 

device 

is the channel name of the device to be attached If a device is not given, the 
-login_channel control argument must be given. 

CONTROL ARGUMENTS 

-login_channel 

specifies attachment to the user's primary login channel. If a device is not specified, 
then the user's login channel is used. This control argument flags this switch for 
reconnection by the process disconnection facility. If the user's login device should hang 
up, this switch will be automatically closed, detached, attached, and opened on the user's 
new login channel when the user reconnects, if permission to use this facility is specified 
in the SAT and PDT for the user. 

-destination DESTINATION 

specifies that the attached device is to be called using the address DESTINATION. In 
the case of telephone auto_call lines, DESTINATION is the telephone number to be 
dialed. See the dial_manager_ subroutine in the Multics Subroutines and 110 Modules 
manual, Order No. AG93, for more details. 

-no_block 

specifies that the device is to be managed asynchronously. The tty_ subroutine will not 
* block to wait for input to be available or output space to be available. This control 

argument should not be used on the login channel, because it will cause the command 
listener to loop calling get_chars. 

-no_hangup_on_detach 

prevents the detach entry point from hanging up the device. This is not meaningful for 
the login channel. 

-hangup_on_detach 

causes the detach entry point to hang up the device automatically. This is not meaningful 
for the login channel. 
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OPEN OPERATION 

Opens the module for stream_input_outpuL 

GET LINE OPERATION 

The get_line operation is not supported. 

CONTROL OPERATION 

The following control orders are supported: 

clear_screen 

clears the entire terminal screen. The info_ptr is null. It is intended for use when the 
screen image may have been damaged due to communications problems, for example. 

get_capabilities 

returns information about the capabilities of the terminal. The info structure is described 
in the description of the "get_capabilities" control order in the window_io_ module. 

get_break_table 

returns the current break table. The info pointer should point to a break table, declared 
as follows (window_control_info.incl.pll): 

del 1 break_table_info aligned based (break_table_ptr) , 
2 version fixed bin, 

2 breaks (0:127) bit (1) unaligned; 

STRUCTURE ELEMENTS 



version 

must be set by the caller to break_table_infc_version_l. (Input) 

breaks 

has a "l"b for each character that is a break character. (Output) 

set_break_table 

sets the break table. The info pointer should point to a break table as defined by the 
get_break_table order, above. By default, the break table has "l"b for all nonprin table 
characters, and "0"b elsewhere. Applications that set the break table must be careful to 
reset it afterwards, and establish an appropriate cleanup handler. 

set_line_speed 

sets the speed of the terminal's connection to Multics. The info_ptr should point to a 
fixed binary number representing the line speed in characters per second. Negative line 
speeds are not allowed. 
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set_term_type 

changes the terminal type. The info pointer should point to a set_term_type_info 
structure, described below. This sets window_status_pending for all windows and sets the 
ttp_change field in the window_status structure along with the screen_invalid. This 
operation re-initializes all the terminal specific video system information such as the 
video sequences, length and width of the screen, and capabilities. It is equivalent to 
doing "window_call revoke; stty -Up new_terminal_type; window_call invoke", except no 
windows are destroyed. The set_term_type_info structure is declared in 
set_term_type_info.incl.pll: 



del 1 



set_term_type_i nf o 


aligned based (sttip) 


2 version 


fixed bin 


2 name char 


(32) unal igned 


2 flags 


unal igned 


3 send_ini tial_str ing 


bit (1) 


3 set_modes 


bit (1) 


3 ignore_l ine_type 


bit (1) 


3 mbz 


bit (33); 



STRUCTURE ELEMENTS 



version 

is the version of this structure. (Input) It must be stti_version_l. 



name 



is the name of the new terminal type. (Input) 



NOTES 



The send_initial_string, set_modes and ignore_line_type flags are all ignored by the video 
system. The initial string will always be sent 

reconnection 

determines the new terminal type (which may or may not be the same as before the 
disconnection). Performs a set_term_type control order to inform the rest of the system 
of the change in terminal type. If the set_term_type fails then the 
video_utils_$turn_of f_login_channel is invoked in an attempt to re-attach tty_. Reconnection 
(a field in window_status) is set to indicate to an application doing get_window_status 
that a reconnection has occurred. 

The window_status_info structure is declared in window_status.incl.pll. 



7-4 



CP51-02 



window_io_ window io 



Name window io 

The window_io_ I/O module supports I/O to a window. In addition to the usual iox_ 
entries, the module provides terminal independent access to special video terminal features, 
such as a moveable cursor, selective erasure, and scrolling of regions. The module provides a 
real-time input line editor and performs output conversion and "MORE" processing. 

Entry points in this module are not called directly by users; rather, this module is accessed 
through the I/O system interfaces iox_ and window_. 

ATTACH DESCRIPTION 

window_io_ switch {-control_args} 

ARGUMENTS 

switch 

is the name of an I/O switch attached to a terminal via the tc_io_ I/O module. The 
window created by this attach operation will be mapped onto the screen of that terminal. 
Use window_$create to attach and open, and use window_$destroy to detach and close 
windows on the login terminal. 

CONTROL ARGUMENTS 

-firstjine LINE_NO 

LINE_NO is the line number on the screen where the window is to begin. If omitted, 
the window starts on the topmost line of the screen (line 1). 

-height N_LINES, -n_Iines N_LINES 

N_LINES is the number of lines in the window. The default is to use all lines to the 
end of the screen. 

-first_column COL_NO 

COL_NO is the column number on the screen where the window is to begin. If omitted, 
the window starts on the leftmost column of the screen (column 1). 

-width N_COLS, -n_columns N_COLS 

N_COLS is the number of the columns in the window. The default is all columns to the 
end of the screen. 

NOTES 

The attach description control arguments must specify a region which lies within the terminal 
screen. If not, the attachment is not made, and the error code video_et_$out_of_terminal_bounds 
is returned. 

When the window is attached, it is cleared and the cursor is left at home. 
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OPEN OPERATION 

The following opening mode is supported: stream_input_outpuL 

PUR CHARS OPERATION 

This operation is used to output a character string to the window. If rawo mode (see below) 
is disabled, the characters are processed according to the output conversions defined for the 
terminal. If necessary, the string is continued on subsequent lines of the window. If output 
passes the last line of the window, the placement of additional lines is controlled by the 
setting of the more_mode mode (see below). If an output line must be erased from the 
window to make room for this new output, and there has been no intervening input in this 
window, and more_mode (see below) is enabled, the user is queried for the disposition of this 
new output (See MORE processing in Section 4.) 

In rawo mode, the characters are written directly to the terminal, without any of the above 
processing. 

GET CHARS OPERATION 

This operation returns exactly one character, unechoed, regardless of the size of the caller's 
buffer. The line editor is not invoked by this call. 

GET LINE OPERATION 

The get_line operation invokes the real-time input line editor, and returns a complete line 

typed by the user. A description of the typing conventions is given in Section 4. The 

put_chars and get_line operations retrieve and reset any statuses that they encounter, so that 

applications that make these calls need not be changed to check for 
video_et_$window_status_pending. 

CONTROL OPERATION 

The control operations below are supported. Note that many of the control operations can be 
issued at command level via io_call commands; these include any control orders that do not 
require an info structure, and those described below. The following relations must hold when 
changing windows (set_window_info). These relations are always true when obtaining 
information about a window (get_window_info): 

< column + width <= screen width 
< line + height <= scrren height 
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get_window_info 

returns information about the position and extent of the window. The info ptr points to 
the following structure (declared in window_control_info.incl.pll): 

del 1 window_position_info based (window_posi tion_info_ptr) , 

2 version fixed bin, 
2 origin, 

3 column fixed bin, 

3 1 ine fixed bin, 
2 extent, 

3 width fixed bin, 

3 height fixed bin; 



STRUCTURE ELEMENTS 



version 

is the version number of 
window_position_info_version_2. 



this structure. (Input) It must be 



column 

is the column of the upper left-hand corner of the window. (Output) If the column 
of the upper left-hand corner is zero, then the first column will be used, to allow 
old programs written when this was a mbz field to run without modification. 



line 



is tu£ line 0i the Upper left-hand corner of the window. (Output) 



width 

is the width of the window (columns). (Output) 

height 

is the height of the window (lines). (Output) 

set_window_info 

causes the window to be relocated or to change size (or both). The info ptr points to 
the same structure used in the "get_window_info" control order. The values have the 
same meaning, but are the new values for the window when setting (Input), and are 
returned by get_window_info (Output). 
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get_window_status, set_window_status 

window status is used to inform the application that some asynchronous event has 
disturbed the contents of the window. When window status is set for a window, all calls 
to window_ will return video_et_$window_status_pending until the status is reset. To 
reset the status, make a get_window_status control order on the switch. The info pointer 
should point to the following structure (declared in window_control_info.incl.pll): 



del 1 window_status_info aligned based (window_status_info_ptr) , 
2 version fixed bin, 

2 status_string bit (36) aligned; 



STRUCTURE ELEMENTS 



version 

is the version of this structure. (Input) It must be window_status„version_l. 

status_string 

is the window status information. (Input) To interpret the actual status_stnng, use 
the include file window_status.incl.pll: 

del 



1 window_status_ 


info 


aligned based (window_status_info_ptr) , 


2 screen_inval i 


"d 


bit (1) unaligned, 


2 async_change 




bit (1) unaligned, 


2 ttp_change 




bit (1) unaligned, 


2 reconnect ion 




bit (1) unaligned, 


2 pad 




bit (32) unaligned; 



STRUCTURE ELEMENTS 

screen_invalid 

indicates that the contents of the window have become undefined. (Input for set. 
Output for get) This will happen, for example, in the event of a 
disconnection/reconnection of the terminal. 

async_change ... u 

indicates that a timer or event call procedure has made a modification to the 
window. (Input for set, Output for get) 

ttp_change 

indicates that the terminal type has changed. (Input for set, Output for get) This 
re-initializes all the terminal specific video system information such as the video 
sequences, length and width of the screen, and capabilities. 
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reconnection 

determines the new terminal type (which may or may not be the same as before the 
disconnection). (Input for set, Output for get) Performs a set_term_type control 
order to inform the rest of the system of the change in terminal type. 



pad 



reserved for future expansion and must be "0"b. 



NOTES 

The get_window_status and get_window_status control orders are available from command level 
and as active functions with the following io_call commands: 

io_call control window_swi ten get_window_status status_key_l 

{status_key_2} N 
io_call control wi ndow_swi tch set_window_status status_key_l 

{status_key_N} 

where status_key_N is either screen_invalid, asynchronous_change, ttp_change, or reconnection. 



get_capabilities 

returns information about the generic capabilities of the terminal. These are the "raw" 
physical characteristics of the terminal. The video system may simulate those that are 
lacking. For example, the system simulates insert and delete characters, but does not 
simulate insert and delete lines. The info ptr should point to the following structure 
(declared in terminal_capabilities.inci.pll): 

del 



1 capabi 1 i ties_info 


a 


ifi 


ned based 


2 version 


f 


xed bin, 


2 screensize, 








3 columns 


f 


xed bin, 


3 rows 


f 


xed bin, 


2 flags, 








3 scrol l_region 


b 


t 


(1) unal, 


3 insert_chars 


b 


t 


(1) unal , 


3 insert_mode 


b 


t 


(1) unal, 


3 delete_chars 


b 


t 


(1) unal, 


3 overprint 


b 


t 


(1) unal, 


3 pad 


b 


t 


(28) unal 


2 1 i ne_speed 


f 


xed bin, 



STRUCTURE ELEMENTS 



version 

is the version number of this structure, 
also declared in the include file. 



(Input) It must be capabilities_info_version_l, 
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columns 

is the number of columns on the terminal. (Output) 

rows 

is the number of rows (lines) on the terminal. (Output) 

scroll_region 

is true if the terminal is capable of scrolling, with insert and delete lines. (Output) 

insert_chars 

is true if the insert_chars function is supported. (Output) 

insert_mode 

is true if the terminal is capable of going into and out of insert mode. (Output) 

delete_chars 

is true if the delete chars function is supported. (Output) 



overprint 
pad 



print 

is true if the terminal is capable of printing overstrike characters. (Output) It is 

currently always set to "0"b (false). 



reserved for future expansion and must be "0"b. 

line_speed 

is the speed of the communications channel to the terminal, in characters per second. 
(Output) 

reset_more 

causes MORE Processing to be reset All lines on the window may be freely discarded 
without querying the user. 

get_editing_chars 

is identical to the operation supported by the tty_ I/O module. 

set_editing_chars 

is identical to the operation supported by the tty_ I/O module. 
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NOTES 

The get_editing_chars and set_editing_chars control orders are available from command level 
and as active functions with the following io_call commands: 

io_call window_switch get_edlting_chars 

io_call control window_swi tch set_editing_chars erase_ki 1 l_characters 

get_more_responses 

returns information about the acceptable responses to MORE processing. The info pointer 
should point to the following structure (declared in window_control_info.incl.pll): 

del 1 more_responses_info aligned based (more_responses_info_ptr) , 

2 version fixed bin, 

2 n_yeses fixed bin, 

2 n_noes fixed bin, 

2 yeses char (32) unaligned, 

2 noes char (32) unaligned; 

STRUCTURE ELEMENTS 

version 

is the version number of this structure and must be set to more_responses_info_version_l, 
also declared in the include file. (Input) 

n_yeses 

is the number of different affirmative responses, from zero to 32. (Output) 

n_noes 

is the number of different negative responses. (Output) 

yeses 

is the concatenation of all the affirmative responses. (Output) Each response is one 
character. Only the first "n_yeses" are valid. 

noes 

is the concatenation of all negative responses. (Output) Each response is one 
character. Only the first "n_noes" are valid. 

set_more_responses 

sets the responses. The data structure is the same as the one used for the 
"get_more_responses" order except that all fields are Input At most, 32 yeses and 32 | 
noes may be supplied. It is highly recommended that there be at least one yes, so that 
output may continue. The "yes" and "no" characters must be distinct. If they are not, 
the error code video_et_$overlapping_more_responses is returned, and the responses are 
not changed. 
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NOTES 



The get_more_response and set_more_response control orders are available from command 
level and as active functions with the following io_call command: 

io_call control window_swi tch get_more_responses 
io_call control window_swi tch set_more_responses yes_responses 
no_responses 

where the yes_responses and no_responses will be used as arguments to the get_more_responses 
control order. If either of the response strings contains blanks or special characters, it must 
be quoted. 

get_more_prompt set_more_prompt 

sets the prompt displayed when a more break occurs. The current more responses can be 
displayed as part of the more prompt, by including the proper ioa_ control codes as part 
of the prompt string. For example the default video system more prompt string is 
"More? ( A a for more; A a to discard output.)". With the default more responses of 
carriage return for more and the delete for discard, the final string displayed is "More 
(RETURN for more; DEL to discard output)." The info pointer should point to the 
following structure (declared in window_control_info.incl.pll): 

del 1 more_prompt_info aligned based (more_prompt_info_ptr) , 
2 version char (8) , 

2 more_prompt char (80) ; 

STRUCTURE ELEMENTS 



version 

is the version number of this structure (currently more_prompt_info_version_l). 
(Input) 

j more_prompt 

is the ioa_ control string to serve as the more prompt (Input for set, Output for 
get) 
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The get_more_prompt and set_more_prompt control orders are available from command level 
and as active functions with the following io_call command: 

io_call control window_swi tch get_more_prompt 

io_call control window_swi tch set_more_-,-ompt prompt_str ing 

where window_switch is a valid window_io_ switch and prompt_string is the ioa_ control 
string described above. 

get_more_handler set_more_handler 

Sets the handler for video system more breaks to the specified routine. The info pointer 
should point to the following structure (declared in window_control_io.incl.pll): 

del 1 more_handler_info aligned based (more_handler_info_ptr) , 

2 version fixed bin, 

2 flags una! igned, 

3 old_handler_valid bit(l), 

3 pad bit (35), 

2 more_handler entry (pointer, bit(l) aligned), 

2 old_more_handler entry (pointer, bit(l) aligned); 

del (more_handler_info_version_3) ; 

fixed bin internal static options (constant) init (3); 

STRUCTURE ELEMENTS 



version 

is the version number of this structure, and must be set to more_handler_inf o_version_3 
(also declared in the include file). (Input) 

morejwndler 

is the entry to be called at a more break. (Input for set) (Output for get) It will 
be passed two arguments, described below. 

old_handler_valid 

is a flag specifying whether some other user-supplied more handler was in effect 
when the order call was made. (Output) (This can only be used with get.) 

old_more_handler 

is the user supplied entry that was acting as more handler before the order call was 
made. (Output) Its value is only defined if the old_handler_valid flag is on. (This 
can only be used with get) 

The more handler routine is called with two arguments. The first is a pointer to a 
structure containing information of interest to a more handler (see below), and the 
second is a flag which the more handler sets to indicate whether or not output should 
be flushed OT*b to continue output, "0"b to flush output). 
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The structure can be found in the include file window_more_handler.incl.pll, and is 
declared as follows: 



del 1 more_info 
2 version 
2 more_mode 
2 window_iocb_prt 
2 more_prompt 
2 more_responses, 
3 n_yeses 
3 n_noes 
3 more_yeses 

3 more_noes 



aligned base (more_info_ptr) , 

f i xed bin, 

fixed bin, /* which flavor */ 

pointer, /* for window that MORE'd */ 

character (80) , /* MORE? */ 

fixed bin, 
fixed bin, 
character (32) unaligned, 

/* at most 32 yeses */ 
character (32) unaligned; 



STRUCTURE ELEMENTS 



version 

is the version number of the structure (declared as more_handler_info_version_2 in 
the include file). (Input) 

window_iocb_ptr 

is a pointer to the iocb for the window in which the more break occurred. (Input) 
Prompt output should be written to this switch, and responses should be read from 
it 

more_mode 

is the current more mode. (Input) Constants for the different more modes are 
declared in the include file window_io_attach_data.incl.pll. 

more_prompt 

is the current more prompt. (Input) This is the string "More? ( A a for more; A a to 
discard output)" and is user-settable. 

more_responses 

is the current set of more responses, and is declared similarly to the more_responses_info 
structure in the get_more_responses order description above. (Input) 
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NOTES 



The get_more_handler and set_more_handler control orders are available from command level 
and as active functions with the following io_call command: 

io_call window_swi tch getjnore_handler 

io_call wi ndow_swi tch set_more_hartdler mcre_handler 

where more_handler is the entryname of the routine to be used as the more handler routine. 
The name is converted to an entry using the user's search rules and is then used as described 
in the set_more_handler control order. 

get_break_table set_break_table 

break table determines action of the get_echoed_chars, get_unechoed_chars, and 
write_sync_read entry points of the window_ subroutine. The array "breaks" has a 1 for 
each character that is to be considered a break. By default, the break table has "l"b for 
all the nonprintable characters, and "0"b elsewhere. Applications that set the break table 
must be careful to reset it afterwards, and establish an appropriate cleanup handler. 

del 1 break_table_info aligned based (break_table_ptr) , 
2 versions fixed bin, 

2 breaks (0:127) bit (1) unaligned; 

STRUCTURE ELEMENTS 



versions 

must be set by the caller to break_table_info_version_l. (Input) 

breaks 

has a "l"b for each character that is a break character. (Input/Output) 

reset_more_handler 

cancels the last user-defined morejiandler. The reset_more_handler control order is 
available from command level with the following io_call command: 

io call control window switch reset more handler 



7-15 CP51-02 



window_io_ 



window_io_ 



get_output_conversion 

this order is used to obtain the current contents of the specified table. The info_ptr 
points to a structure like the one described for the corresponding "set" order below, 
which is filled in as a result of the call (except for the version number, which must be 
supplied by the caller). If the specified table does not exist (no translation or conversion 
is required), the status code error_table_$no_table is returned. 

set_output_conversion 

provides a table to be used in formatting output to identify certain kinds of special 
characters. The info_ptr points to the following structure (declared in tty_convert.incl.pll). 
If the info_ptr is null, no transaction is to be done. 



del 1 cv_trans_struc 
2 version 
2 default 
2 cv_trans 
3 value 



al igned 
fixed bin, 
fixed bin, 
al igned 
(0:255) fixed 



bin (8) unal igned 



STRUCTURE ELEMENTS 



version 

is the version number of the structure. It must be 2 and declared in tty_convert.incl.pll. 

default 

indicates, if nonzero, that the table is the one that was in effect before video was 
invoked. 

values 

are the elements of the table. This table is indexed by the value of a typed input 
character, and the corresponding entry contains the ASCII character resulting from 
the translation. 

get_special 

is used to obtain the contents of the special_chars table currently in use. The info_ptr 
points to the following structure (defined in tty_convert.incl.pll): 

del 1 get_special_info_struc aligned 
2 area_ptr ptr, 

2 table_ptr ptr; 



7-16 



CP51-02 



window_io_ window io 



STRUCTURE ELEMENTS 



area_ptr 

points to an area in which a copy of the current special_chars table is returned. 
(Input) 

table_ptr 

is set to the address of the returned copy of the table. (Output) 

set_special 

provides a table that specifies sequences to be substituted for certain output characters, 
and characters that are to be interpreted as parts of escape sequences on input Output 
sequences are of the following form (defined in tty_converLincl.pll): 

del 1 c_chars based aligned, 

2 count fixed bin (8) unaligned, 
2 chars (3) char (1) unaligned; 

STRUCTURE ELEMENTS 



count 

is the actual length of the sequence in characters (0<= count <=3). If count is zero, 
there is no sequence. 
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chars 



are the characters that make up the sequence. The info_ptr points to a structure of 
the following form (defined in tty_convert.incl.pll): 



del 1 special_chars_struc 

2 version 

2 default 

2 special_chars 
3 nl_seq 
3 cr_seq 
3 bs_seq 
3 tab_seq 
3 vt_seq 
3 ff_seq 
3 printer_on 
3 printer_off 
3 red_r ibbon_shif t 
3 black_r ibbon_shif t 
3 end_of_page 
3 escape_length 
3 not_edi ted_escapes 



3 edi ted_escapes 



3 input_escapes 
U len 
it str 



input_resul ts 
1* pad 
k str 



al igned based, 
f i xed bin, 
f i xed bin, 

al igned 1 ike 
al igned 1 ike 
al igned 1 ike 
al igned 
al igned 
al igned 
al igned 
al igned 
al igned 
al igned 
al igned 



c_chars, 
c_chars, 
c_chars, 
c_chars, 
c_chars, 
c_chars, 
c_chars, 
c_chars, 
c_chars, 
c_chars, 
c chars, 



like 

like 

like 

like 

like 

like 

like 

like 
fixed bin, 

(sc_escape_len refer 
(special_chars.escape_length)) 

1 ike c_chars, 
(sc_escape_len refer 
(spec i a l_chars . escape_l ength) ) 

1 ike c_chars, 
al igned, 

fixed bin (8) unaligned, 
char (sc_input_escape_len refer 
(special_chars. input_escapes. len) ) 

unal igned, 
al igned, 

bit (9) unaligned, 
char (sc_input_escape_len refer 
(special_chars. input_escapes. len) ) 
unal igned; 



NOTES 

Video ignores cr_seg, bs_seg, tab_seg, vt_seg, ff_seg, printer_on, printer_off, end_of_page, 
input_escapes, and input results. 
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STRUCTURE ELEMENTS 



version 

is the version number of this structure. It must be 1. 

default 

indicates, if nonzero, that the default values for the current terminal type and baud 
rate are to be used and that the remainder of the structure is to be ignored. 

nl_seq 

is the output character sequence to be substituted for a newline character. The 
nl_seq. count generally should be nonzero. 

cr_seq 

is the output character sequence to be substituted for a carriage-return character. If 
count is zero, the appropriate number of backspaces is substituted. However, either 
cr_seq.count or bs_seq.count should be nonzero (i.e., both should not be zero). 

bs_seq 

is the output character sequence to be substituted for a backspace character. If count 
is zero, a carriage return and the appropriate number of spaces are substituted. 
However, either bs_seq.count or cr_seq.count, should be nonzero (i.e., both should 
not be zero). 

tab_seq 

is the rmtniit rhnrartpr cmiupticp tn Vu» ciiVictitiito/1 f/vr i hnn^nntol toV. ie ~~,,„+ ;*. 

zero, the appropriate number of spaces is substituted. 

vt_seq 

is the output character sequence to be substituted for a vertical tab. If count is 
zero, no characters are substituted. 

ff_seq 

is the output character sequence to be substituted for a formfeed. If count is zero, 
no characters are substituted. 

printer_on 

is the character sequence to be used to implement the printer_on control operation. 
If count is zero, the function is not performed. 

printer_off 

is the character sequence to be used to implement the printer_off control operation. 
If count is zero, the function is not performed. 

red_ribbon_shift 

is the character sequence to be substituted for a red-ribbon-shift character. If count 
is zero, no characters are substituted. 
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black_ribbon_shift 

is the character sequence to be substituted for a black_ribbon_shift character. If 
count is zero, no characters are substituted. 

end_of_page 

is the character sequence to be printed to indicate that a page of output is full. If 
count is zero, no additional characters are printed, and the cursor is left at the end 
of the last line. 

escape_length 

is the number of output escape sequences in each of the two escape arrays. 

not_edited_escapes 

is an array of escape sequences to be substituted for particular characters if the 
terminal is in " A edited" mode. This array is indexed according to the indicator found 
in the corresponding output conversion table (see the description of the 
set_output_conversion order above). 

edited_escapes 

is an array of escape sequences to be used in edited mode. It is indexed in the 
same fashion as not_edited_escapes. 

input_escapes 

is a string of characters each of which forms an escape sequence when preceded by 
an escape character. 

input_results 

is a string of characters each of which is to replace the escape sequence consisting 
of an escape character and the character occupying the corresponding position in 
input_escapes. 

get_token_characters, set_token_characters 

changes the set of characters that are used by the video system input line editor to 
define a word for such requests as ESC DEL. The set of characters supplied in the 
structure replace the existing set of characters. The info_ptr points to the following 
structure (declared in window_control_info.incl.pll): 

del 1 token_characters_info aligned based 

(toker_characters_info_ptr) , 
2 version char (8) , 

2 token_characters_count fixed bin, 
2 token_characters char (128) unaligned; 

STRUCTURE ELEMENTS 



version 

is the version string for this structure. (Input) Its current value is 
token_characters_info_version_l, also declared in the include file. 

7-20 CP51-02 



window_io_ window io 



token_charaeters_count 

is the number of characters in the token_characters string. (Input) 

token_characters 

is a character string containing the new set of token characters. (Input) 

NOTES 

The set_token_characters and get_token_characters control orders are available from commandjevel 
and as active functions with the following io_call commands: 

io_call control wlndow_swi ten get_token_characters 

io_call control window_swi tch set_token_characters token_char_str ing 

where token_char_string is a character string containing the new set of token characters. 
get_token_character returns its result as a string if it was invoked as an active function, 
otherwise it prints out the token characters. 

get_editor_key_bindings 

returns a pointer to the line_editor_key_binding structure describing the key bindings. 
io_call support points out the pathname of each editor routine, listing only the names of 
builtin requests in capital letters, with the word "builtin" in parentheses. The control 
order prints or returns current information about the key bindings. Use the 
set_editor_key_bindings control order to change the bindings. This control order prints or 
returns current information about the key_bindings. Use the set_editor_key_bindings 
control order to change the bindings. 

The info_ptr points to the following structure (declared in window_control_info.incl.pll): 

del 1 get_edi tor_key_bindings_info aligned based 

(get_ed i tor_key_b i nd i ng_i nf o_ptr) , 

2 version char (8) , 
2 flags, 

3 entire_state bit (1) unaligned, 

3 mbx bit (35) unaligned, 

2 key_binding_info_ptr ptr, 

2 enti re_state_ptr ptr; 

STRUCTURE ELEMENTS 



version 

is get_editor_key_binding_info_version_l. (Input) 

entire_state 

is "l"b if the entire state is desired, "0"b if only information about certain 
keybindings is desired. (Input) 
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key_binding_info_ptr 

if entire_state - "0"b, then this points to a lme_editor_key_bmding_structure. (Input) 
The bindings component of this structure is then filled in based upon the value of 
each key_sequence supplied. 

entire_state_ptr 

is set to point to the "state" of the key bindings, if entire_state = "l"b. (Output) 
This is suitable input to the set_editor_key_bindings control order. 

NOTES 

The get_editor_key_bindings control order is available from command level and as an active 
function with following io_call command: 

io_call control window_swi ten get_edi tor_key_bindings 

The get_editor_key_bindings control order prints or returns information about a key binding. 
When you use it as an active function the information is returned in a form suitable as 
arguments to the set„editor„key_bindings control order. 

set_editor_key_bindings 

A line editor routine is bound to a sequence of keystrokes via the set_editor_key 
bindings control order. The sequence of characters that triggers an editor request may be 
of any length, with multiple-key sequences working like the Emacs prefix characters. 
This allows the use of terminal function keys (which often send three or more character 
sequences) to invoke line editor requests. More than one binding can be set in one 
invocation of this control order. 

The info_ptr points to the following structure (declared in window_control_info.incl.pll): 

del 1 set_edi tor_key_bindings_info aligned based 

(set_ed i tor_key_b i nd i ngs_i nf o_ptr) , 
2 version char (8) , 

2 flags, 

3 replace bit (1) unaligned, 

3 update bit (1) unaligned, 

3 pad bit (}k) unaligned. 

2 key_binding_info_ptr; 

STRUCTURE ELEMENTS 



version 

is the version of the structure. (Input) It must be set_editor_key_bindings_info_version_l. 

replace 

if "l"b then key_binding_info is considered to be returned by a previous 
get_editor_key_bindinp operation with entire_state = "l"b and will be used to 
replace the keybinding state of the editor. (Input) 
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update 

if "l"b then key_binding_info_ptr is considered a pointer to a 
line_editor_key_binding_info structure, which will be used to update the keybinding 
state of the editor. (Input) 

Note: only one of replace and update may be true, but at least one of them must 
be true. 

key_binding_info_ptr 

is a pointer received from get_editor_key bindings operation or a pointer to a 
line_editor_key_binding_info structure, depending on the value of the replace and 
update flags. (Input) 

Notes on freeing: The video system's internal data structures are freed at the following 
times: video system revocation and when a set_editor_key_bindings control order with 
replace = "l"b is done. 

NOTES 

The set_editor_key_bindings control order is available from command level and as an active 
function with the following io_call command: 

io_call control window_swi tch set_edi tor_key_bindings key_sequencel 

{user_routinel} {control_argsl} key_sequenceN 

{user_routi neN} {control_argsl} {control_argsN} 

where user_routine is the name of a user-written editor request 

control args are: 

-external user_routine 
-builtin bui 1 tin_request_name 
-numarg_act i on numarg_act i on_name 

The line_editor_key_bindings_info structure is described in Section 7. 

At least one user_routine or one of -external/-builtin must be specified for each key 
sequence, with the rightmost editor request specifier taking precedence (for example, io 
control window_switch set_editor_key_binings foo -builtin FORWARD_word,) will bind control 
-a to the forward word builtin, not the user routine foo. 



numarg_action_name 

the type of automatic numeric argument to be taken when the editor routine is invoked, 
must be one of the following and can only be given for external editor routines 

REPEAT 

(the default is PASS). This can be entered in upper or lower case. Call the user routine 
n times, where n is the numeric argument supplied by the user. 
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REJECT 

ring the terminal bell and don't call the user routine if a numeric argument is given. 

PASS 

pass any numeric argument to the user routine, without any other action. 

IGNORE 

same as PASS but implies the user routine will not make use of the numeric argument 

-name STR 

specifies the name of the editor command being assigned to the key. If this is the null 
string, then a default name is used (for builtins this is the name of the builtin, otherwise 
it is segnameSentrypoint). STR must be quoted if it contains whitespace. 

-description STR 

specifies a description string to be associated with the key binding. If this is the null 

string, a default description is used. The defaults can be found in the include file 

window_editor_values.incl.pll. STR must be quoted if it contains whitespace. 

-info_pathname PATH 

specifies an info segment pathname to be associated with this key binding. This info 
segment is expected to have more information about the editor_routine. If this is not 
specified, it defaults to >doc>info>video_editing.gi.info if -builtin, otherwise no info 
segment is associated with the key. The info suffix is assumed on PATH. 

MODES OPERATION 

The modes operation is supported by window_io_. The recognized modes are listed below. 
Some modes have a complement indicated by the circumflex character ( A ) that turns the mode 
off (e.g. A more). For these modes, the complement is displayed with that mode. Some modes 
specify a parameter that can take on a value (e.g. more_mode). These modes are specified as 
MODE= VALUE, where MODE is the name of the mode and VALUE is the value it is to be 
set to. Parameterized modes are indicated by the notation (P) in the following description: 

more, A more 

Turns MORE processing on. Default is on. If A pl is set before you invoke the video 
system, A more will be set when you invoke the video system. 

more_mode = STR 

controls behavior when the window is filled. The value for STR may be one of the 
following: 

clear 

the window is cleared, and output starts at the home position. 

fold 

output begins at the first line and moves down the screen a line at a time replacing 
existing text with new text Prompts for a MORE response when it is about to 
overwrite the first line written since the last read or MOPvE break. 
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scroll 

lines are scrolled off the top of the window, and new lines are printed in the space 
that is cleared at the bottom of the screen. This is the default for full width 
windows on all terminals capable of scrolling. 

wrap 

output begins at the first line and moves down the screen a line at a time replacing 
existing text with new text Prompts for a MORE response at the bottom of every 
window of output This is the default for all terminals that are incapable of 
scrolling or when using partial width windows. 

vertsp, A vertsp 

is only effective when more mode is on. When vertsp mode is on, output of a FF 
or VT will cause an immediate MORE query. When you invoke the video system, it 
copies the current setting of this mode before attaching the window_io_ module. The 

default is A vertsp. 

rawo, A rawo 

causes characters to be output with no processing whatsoever. The result of output in 
this mode is undefined. 

can, A can 

causes input lines to be canonicalized before they are returned. When you invoke the 
video system, it copies the current setting of this mode before attaching the 
window_io_ module. The default is on. 

ctLchar, A ctLchar 

specifies that ASCII control characters that do not cause newline or linefeed motion 
are to be accepted as input except for the NUL character. If the mode is off all 
such characters are discarded. When you invoke the video system, it copies the 
current setting of this mode before attaching the window_io_ module. The default is 
off. 

edited, A edited 

suppresses printing of characters for which there is no defined Multics equivalent on 
the device referenced. If edited mode is off, the 9-bit octal representation of the 
character is printed. When you invoke the video system, it copies the current setting 
of this mode before attaching the window_io_ module. The default is off. 

erkl, A erkl 

controls the editing functions of get_line. When you invoke the video system, it 
copies the current setting of this mode before attaching the window_io_ module. The 
default is on, which allows erase and kill processing and the additional line editor 
functions. 
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esc, A esc 

controls input escape processing. When you invoke the video system, it copies the 
current setting of this mode before attaching the window_io_ module. The default is 
on. 

rawi, A rawi 

acts as a master control for can, erkl, and esc. If this mode is on, none of the 
input conventions are provided. The default is on. 

11 = STR 

is the width of the window, in characters, and it can only be changed with the 
set_window_info control operation. 

pi = STR 

is the height of the window (i.e., number of lines), and it can only be changed with 
the set_window_info control operation. 

red, A red 

controls interpretation of red shift and black shift characters on output. When you 
invoke the video system, it copies the current setting of this mode before attaching 
the window_io_ module. The default is A red, which ignores them. In red mode, the 
character sequence given in the TTF is output The effect is undefined and 
terminal-specific. In some cases, "red shifted" output appears in inverse video, but 
this is not guaranteed. 

CONTROL OPERATIONS FROM COMMAND LEVEL 

Those control operations which require no info_ptr and those additional orders described 
above may be performed from command level using the io_call command, as follows: 

io call control switch name control order 



ARGUMENTS 

switch_name 

is the name of the I/O switch. 

control_order 

can be any control order described above under "Control Operation" that can accept a 
null info_ptr. 
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SECTION 8 
FORTRAN INTERFACE 



This section contains descriptions of the FORTRAN subroutine interface to the menu 
and video software. Two sample FORTRAN programs are provided that illustrate menu 
creation using automatic window management, and the FORTRAN video interface capabilities. 

In the FORTRAN environment, window management can be performed automatically. By 
using arguments to the FORTRAN window management functions ft_menu_$initl, ft_menu_$init2, 
and ft_menu_$terminate, applications that do not require sophisticated window management 
can employ automatic window management. When using automatic window management, your 
application works in two-window mode: the window in which the menu is displayed and the 
user i/o window. 

If your application requires greater window management capabilities, the menu interface 
capability lets you build menu applications using the ft_window_$create, ft_window_$destroy, 
ft_window_$clear, and ft_window_$change capabilities. 

Of course, FORTRAN applications, can still use command or PL/1 video management 
capabilities. 

Note that it is not possible to call the ft_menu_ routines with both ANSI77 and 
ANSI66 character strings. Currently, only ANSI77 character strings are allowed. 
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Name: ft menu 

The ft_menu_ subroutine allows a FORTRAN program to use the Multics menu facility 
(menu J. Through ft_menu_ a FORTRAN program may create a menu object, display the 
menu, and get a user-entered selection from a menu. Once a menu object has been created, 
the FORTRAN program can use this menu object by referencing it via a menu-id returned to 
the caller when the menu object was created or when a stored menu object was retrieved. 

The functionality available is provided through the various entry points defined below. Also 
refer to the FORTRAN include file at the end of this section. 

Entry: ft_menu_$create 

Utilized to create a menu object It returns a menu identifier (menu_id) which is 
subsequently used to reference the menu object 

USAGE 

declarations: 

character*nl choices (ml) 

character*n2 headers (m2) 

character*r>3 trailers (m3) 

character*l keys (mU) 

character*! pad_char 

integer menu_f ormat (6) 

i nteger menu_needs (3) 

integer menu_id 

i nteger code 

call ft_menu_$ create (choices, headers, trailers, pad_char, menu_format, 
key, menu_needs, menu_id, code) 

STRUCTURE ELEMENTS 

choices 

is an array of character variables which are the text of the options that the user wishes 
to display in the menu. (Input) nl is the length, in characters, of the longest character 
string comprising the text of an option, ml is the extent of the array, i.e., the number 
of options in the menu being described. This array must be at least of extent 1. 
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headers 

is an array of character variables to be displayed at the top of the menu. (Input) n2 is 
the length, in characters, of the longest header specified. m2 is the extent of the array, 
i.e., the number of headers (lines) desired. At least one header must be specified (if the 
first variable is set to blanks, no headers will be used). 

trailers 

is an array of trailers (displayed immediately below the menu). (Input) n3, m3, are 
analogous to n2, m2 respectively. 

menu_format 

is an array, which specifies the format of the menu being created. (Input) Prior to 
calling this entry point, the FORTRAN programmer is responsible for setting the 
following variables: 

menu_format (menu_version) = version number of menu_ 

(currently, only version 1 is defined). 
menu_format (max_width) = maximum width of the window 

on which the menu will be displayed. 
menu_format (max_heigth) = maximum height of window 

on which menu is to be displayed. 
menu_format (no_of_columns) = number of columns to be used 

by the menu manager to display the options. 
menu_format (center_headers) = or 1 ; = no, 1 = yes. 
menu_format (center_trai lers) = or 1 ; = no, 1 = yes. 

pad_char 

is the character that the menu facility will display at the right and left of a centered 
header or trailer to fill out the line. (Input) 

keys 

is an array (maximum value of m4 is 61) that identifies the keystroke to be associated 
with each choice. (Input) This array must be at least as long as the number of choices 
in the menu. Each element in the array must be unique. 

menu_needs 

an array that contains menu related information on successful execution of call. (Output) 

Returned information: 

menu_needs (1 ines_needed) the number of lines required 

to display the menu. 
menu_needs (width_needed) the number of columns required 

to display the menu. 
menu_needs (no_of_options) the number of options defined 

in the menu. 
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menu_id 

the menu identifier (i.e., the menu object "identifier"). (Output) It must not be altered 
in any way by the application program. 

code 

return code. (Output) (See Appendix B.) 

Entry: ft menu Sdelete 

Deletes a menu object from a given value segment. (See ft_menu_$store.) 

USAGE 

declarations: 

character*l68 dir_name 

character*32 entry_name 

character*32 menu_name 

integer code 

call f t_menu_$delete (dir_name, entry_name, menu_name, code) 
STRUCTURE ELEMENTS 



dir_name 

pathname of the directory containing the menu object. (Input) 

entry_name 

entry name of value segment containing the menu object. (Input) The suffix "value" need 
not be specified. 

menu_name 

name used to identify the menu object when the menu object was stored. (Input) 

code 

return code. (Output) (See Appendix B.) 

Entry: ft menu $describe 

Returns information about a menu object. It returns the number of options in the menu, the 
number of lines and number of columns required to display the menu. It is primarily used 
to determine if the menu can be displayed in a given window. 
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USAGE 

declarations: 

integer menu_id 

i nteger menu_needs (3) 

integer code 

call f t_menu_$descr ibe (menu_id, menu_needs, code) 
STRUCTURE ELEMENTS 



menu_id 

the menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input) 

menu_needs 

an array into which menu related information is returned. (Output) 

Returned information: 

menu_needs (1 ines_needed) the number of lines required 

to display the menu. 

menu_needs (width_needed) the number of columns needed 

to display the menu. 

menu_needs (no_of_options) the number of options defined 

in the menu. 



code 

return code. (Output) (See Appendix B.) 

Entry: ft menu $destroy 

Invoked to delete a menu object from storage. (Not to be confused with ft_menu_$delete, 
which deletes the menu object from a value segment.) Deleting the menu object has no 
effect on the screen contents. 

USAGE 

declarations: 

integer menu_id 
integer code 



cal 1 f t_menu_$destroy (menu_id, code) ; 
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STRUCTURE ELEMENTS 

menu_id 

menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input/Output) Set to 
an invalid value on return to prevent the old menu_id from being accidentally used. 

code 

return code. (Output) (See Appendix B.) 

Entry: ft_menu Sdisplay 

Invoked to display a menu in a given window. 

USAGE 

declarations: 

integer window_id 
integer menu_id 
integer code 

call ft_menu_$di splay (window_id, menu_id, code) 
STRUCTURE ELEMENTS 

window_id 

a window identifier returned by ft_window_$create. (Input) If usage_mode = this 
argument will be ignored (see ft_menu_$init2). 

menu_id 

menu identifier returned when the menu object was created or retrieved. (Input) 

code 

return code. (Output) (See Appendix B.) 

Entry: ft_menu_$get_choice 

Returns the choice made by the user, i.e., an integer representing either the menu item 
chosen or the function key (or its equivalent escape sequence) entered. 
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USAGE 

declarations: 

character*nl function_key_info 

integer window_id 

integer menu_id 

integer fkeys 

integer selection 

integer code 

call ft_menu_$get_choice (window_id, menu_id, function_key_info, fkeys, 
selection, code) 

STRUCTURE ELEMENTS 



window_id 

a window identifier returned by ft_window_$create. (Input) If usage_mode = this 
argument will be ignored, (see ft_menu_$init2) 

menu_id 

menu identifier returned by ft_jnenu_$create or ft_menu_$retrieve. (Input) 

function_key_info 

a character variable (nl as required) used to specify the role of function keys (if they 
exist for the terminal being used) or an equivalent set of escape sequences if the 

terminal does not have function Vp.vs nr nnt tVip fnnrrirm V<»vc reni"«"H iw tVio 

application. (Input) The objective is to let the application use the terminal's function 
keys if possible, else specify key sequences to be used to simulate function keys. Each 
character in the string corresponds to one function key. If the character is a space, then 
it is not relevant if the corresponding function key exists or not. If the character is not 
a space, that character will be used to simulate a function key if the terminal does not 
have function keys. If the terminal does not have a function key for every non-space 
character in the string, then function keys will be simulated. Thus, the string " ?p q" 
means that the caller does not care whether the terminal has function key or 3, but 
the caller does wish to use function keys 1,2, and 4. If any of these 3 function keys is 
not present on the terminal, then esc-? will substitute for Fl, esc-p will substitute for 
F2, and esc-q will substitute for F4. 

fkeys 

if fkeys = 1 user entered a function key or escape sequence if fkeys = user selected 
an option (Output) 

selection 

is an integer representing the choice made by the user. (Output) If the user has chosen 
an option, it is a number between 1 and the highest defined option. If the user has 
entered a function key, or escape sequence simulating a function key, it is the number 
associated with the function key. 
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code 

return code. (Output) (See Appendix B.) 

Entries: ft menu $initl, ft menu $init2 

These must be the first calls made to the menu manager. They set up the necessary 
environment for the menu application and return information concerning the user i/o window. 

USAGE 

declarations: 

integer code 

i nteger usage_mode 

call f t_menu_$ini tl () 

cal 1 f t_menu_$ini t2 (usage_mode,user_wi ndow_l i nes,user_window_columns, 
user_w i ndow_i d , code) 

STRUCTURE ELEMENTS 



usage_mode 

usage_mode = means that the caller does not wish to do any window management at 
all. (Input) When he/she wishes to display a menu, the window required will be 
automatically created. This means that the application will operate in a two window 
mode, the window containing the menu, and the user_io window. Both windows will be 
managed automatically for the user. If the user specifies this mode, all calls to the 
ft_window_ subroutine will be ignored and will return an appropriate error code. See 
Error Code Handling (Appendix B), below. All calls to the ft_menu_ subroutine that 
require a window identifier will ignore the user provided window_id. 

usage_mode = 1 means that the user wishes to define the number and characteristics of 
the windows to be used in the application. Thus, calls to ft_window_ will be supported 
and, for the entry points of ft_menu_ that require a window identifier, the caller must 
use a legal window_id (returned by ft_window_$create). 

user_window_lines 

the number of lines (rows) in the user i/o window at the time the user invokes 
ft_menu_$init (which must be the first call to the menu manager in the application). 
(Output) Undefined if usage_mode = 0. 

user_window_columns 

the number of columns of the user i/o window when ft_menu_$init invoked. (Output) 
Undefined if usage_mode = 0. 

user_window_id 

window identifier of the user i/o window. (Output) Undefined if usage_mode = 0. 

code 

return code (See Appendix B.) (Output) 
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Entry: ft menu Slist 

Used to list the menu object(s) stored in value segment The names selected are those that 
match a user provided string. 

USAGE 

declarations; 

character*l68 dir_name 

character*32 names_array (ml) 

character*32 entry_name 

character*32 match_str ing 

integer no_of_matches 

integer code 

call ft_menu_$l ist (dir_name, entry_name, match_str ing, no_of_matches, 
names_array, code) 

STRUCTURE ELEMENTS 

dir_name 

pathname of directory containing the menu object. (Input) 

entry_name 

entry name of value segment containing the menu object. (Input) The suffix "value" need 
not be specified. 

match_string 

a character variable that is to be used as the selection criteria to determine what menu 
object, if any, is contained in the specified value segment that match (or contain) this 
string (Input) If set to space(s), all names returned. 

no_of_matches 

the number of matches found. (Output) If none, then is is 0. 

names_array 

an array, of extent ml. (Output) The user should insure that ml is sufficiently large to 
contain all matches that may be found. Contains the names of all menu objects, in the 
specified value segment, that match the character string match_string 

code 

return code. (Output) (See Appendix B.) 
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Entry: ft_menu_$retrieve 

Used to retrieve a menu object previously stored via the ft_menu_$store. Once retrieved, the 
user can reference the menu object via the menu identifier (menu_id). 

USAGE 

declarations: 

character*l68 dir_name 

character*32 entry_name 

character*32 menu_name 

integer menu_id 

integer code 

call f t_menu_$retr ieve (dir_name, entry_name, menu_name, menu_id, code) 
STRUCTURE ELEMENTS 



dir_name 

pathname of the directory containing the menu object. (Input) 

entry_name 

entry name of value segment containing menu object (Input) The suffix "value" need not 

be specified. 

menu_name 

name of the menu object used when the object was stored. (Input) 

menu_id 

is the menu id returned by the call. (Output) It is used as the menu object identifier. 

code 

return code. (Output) (See Appendix B.) 

Entry: ft_menu $store 

Used to store a menu object in a specified value segment. 

USAGE 

declarations: 

character*l68 dir_name 

character*32 entry_name 

character*32 menu_name 

integer create_seg 

integer menu_id 



j* 



nteger code 
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call f t_menu_$store (di r_name,entry_name, menu_name, create_seg, 
menu_ld f code) 

STRUCTURE ELEMENTS 

dir_name 

pathname of directory into which the menu object is to be placed. (Input) 

entry_name 

entry name of value segment into which the menu object is to be placed. (Input) The 
suffix "value" need not be specified. 

menu_name 

it is the name to be assigned to the stored menu object (Input) 

create_seg 

create_seg = means do not store if value segment identified by entry_name does not 
already exist. (Input) 

create_seg = 1 means create value segment, if it does not already exist, and store menu 
object in it 

menu_id 

it is the menu object identifier returned when ft_menu_$create or ft_menu_$retrieve was 
called. (Input) 

code 

return code. (Output) (See Appendix B.) 

Entry: ft_menu_$terminate 

Must be the last call to the menu manager in the menu application. It will remove the 
special environment created by ft_menu_$initl and ft_menu_$init2. 

USAGE 

declarations: none 

call ft_menu_$ terminate () 
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FORTRAN INCLUDE FILE 

This include file contains the following declarations: 

external ft_menu_$ create (descriptors) 

external f t_menu_$delete (descriptors) 

external f t_menu_$descr ibe (descriptors) 

external f t_menu_$destroy (descriptors) 

external ft_menu_$di splay (descriptors) 

external f t_menu_$get_choice (descriptors) 

external f t_menu_$ i n i t 1 (descriptors) 

external f t_menu_$i ni t2 (descriptors) 

external f t_menu_$l ist (descriptors) 

external ft_menu_$ retrieve (descriptors) 

external ft_menu_$ store (descriptors) 

external f t_window_$change (descriptors) 

external f t_window_$create (descriptors) 

external f t_wi ndow_$destroy (descriptors) 

integer menu_version 

integer max_width 

integer max_height 

integer no_of_columns 

i nteger 1 i nes_needed 

integer width_needed 

i nteger no_of_opt i ons 

integer center_headers 

i nteger center_tra i 1 er s 

integer user_window_id 

integer user_window_l i nes 

integer user_wi ndow_columns 

parameter (menu_version = 1) 

parameter (max_width = 2) 

parameter (max_height = 3) 

parameter (no_of _co i umns = It) 

parameter (center_headers = 5) 

parameter (center_trai lers = 6) 

parameter (1 ines_needed = 1) 

parameter (width_needed = 2) 

parameter (no_of_options = 3) 
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Name: ft__window 

This is the basic video interface subroutine to be used by FORTRAN to create/destroy /change 
windows. (This subroutine should not be called if usage_mode = (see ft_menu_$init2)). 

Its facilities are available through the following entry points. 

Entry: ft window__$change 

This entry point is used to change the size of an existing window. The size of a window can 

always be "shrunk", however it can be increased only it does not overlap with another 

defined window. (This entry point should not be called if usage_mode = (see 
ft_menu_$init2).) 

USAGE 

declarations: 

integer window_id 

integer f i rst_l ine 

integer height 

integer code 

call f t_window_$change (window_id, first_line, heigth, code) 
STRUCTURE ELEMENTS 



window_id 

window identifier returned by ft_window_$create (or by ft_menu_$init in the case of the 
user i/o window). (Input) 

first_line 

new first line number for the window being changed. (Input) Positive integer. 

height 

new height for the window being changed. (Input) Positive integer. 

code 

return code. (Output) (See Appendix B.) 



8-13 CP51-02 



ft window ft_window_ 



Entry: ft window Sclear window 

Used to clear a specified window. 

USAGE 

declarations: 

integer window_id 

integer code 

call f t_window_$clear_window (window_id, code) 
STRUCTURE ELEMENTS 



window_id 

The window identifier (returned by ft_window_$create) of the window to be cleared. 
(Input) 

code 

return code. (Output) (See Appendix B.) 

Entry: ft window Screate 

Used to create a new window on the terminal screen. (This entry point should not be called 
if usage_mode = 0.) (see ft_menu_$init2) 

USAGE 

declarations: 

character*32 switch_name 

integer window_id 

integer first_line 

integer height 

integer code 

call f t_window_$create (first_line, height, switch_name, window_id, 
code) 

STRUCTURE ELEMENTS 



first_line 

is the line number where the window is to start (Input) 

height 

the number of lines used by the window, i,e, 5 its height (Input) 
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switch_name 

the name that the caller wishes to associate with the switch. (Input) (The caller mav use 
the switch name, for example, in the FORTRAN "open" statement) 

window_id 

the returned id of the window just created. (Output) It must not be altered in any way 
by the application program. 

code 

return code. (Output) (See Appendix B.) 

Entry: ft_window_$destroy 

Used to destroy a previously created window. (This entry point should not be called if 
usage_mode = (see ft_menu_$init2).) 

USAGE 

declarations: 

integer window_id 
integer code 

call f t_window_$destroy (window_id, code) 
STRUCTURE ELEMENTS 

window_id 

window identifier (returned by the ft_window_$create). (Input/Output) It is reset to an 
illegal value by this call. 

code 

return code. (Output) (See Appendix B.) 

FORTRAN MENU APPLICATION EXAMPLES 

In the following two FORTRAN examples, a "Message" menu application is created that 
allows you to display, print, discard, or forward messages. Example 1 is a simple FORTRAN 
program that interfaces with the Multics menu manager via the ft_menu_ routine. Note in 
Example 1 that window management functions are called automatically through arguments in 
the ft_menu_$init2 subroutine. 

Example 2 is a FORTRAN program that interfaces with the Multics menu manager through 
ft_menu_routine; in example 2, however, window management functions are performed bv the 
ft_window_ routine. 
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EXAMPLE J: 

In this example, all window management is done automatically. 

subroutine tes teasel () 

% include f t_menu_dc 1 s 

external f t_menu_$ i n i t 1 (descriptors) 
external f t_menu_$ini t2 (descriptors) 
character*15 choices (6) 
headers (1) 



character*12 

character*27 

character*! 

character*l68 

character*32 

character*32 

character*! 2 

character*32 

character*9 

integer 

integer 

integer 

integer 

i nteger 

integer 

integer 

integer 

i nteger 

integer 

integer 



trai lers (1) 

keys (6) 

d i r_name 

entry_name 

menu_name 

f unct i on_key_i nf o 

swi tch_name 

ME 

create_seg 

no_of_matches 

w i ndow_ i d 

fkeys 

selection 

usagejnode 

menu_f ormat (6) 

menu_needs (3) 

menu_id 

code 

zero 



external com err (descriptors) 



integer 


too_f ew_keys 


integer 


bad_arg 


integer 


keys_not_un i que 


HE = "testcase!" 


zero = 




choices (1) 


= "Display Message" 


choices (2) 


= "Print Message" 


choices (3) 


= "Discard Message" 


choices CO 


= "Forward Message" 


choices (5) 


= "Reply Message" 


choices (6) 


= "List Messages" 


headers (!) 


= "READ MAIL" 


trai lers (1) 


i = "Press Fl (or esc 


keys(l) = ' 


;-,;; 


keys (2) = ' 


'2" 



-q) to qui t" 
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keys (3) ■ "3" 

keys (4) - "it" 

keys (5) = "5" 

keys (6) = "6" 

pad_ctiar - "-" 

menu_format (menu_version) = 1 

menu_format (max_width) = 79 

menu_format (max_height) = 10 

menu_format (no_of_columns) = 2 

menu_f ormat (center_headers) = 1 

menu format (center trailers) = 1 



code = 

usage_mode = ! Window management will be done automatically 
! by the system, i.e., usage_mode is set to 0. 
! by the system, i.e., usage_mode is set to 0. 
call f t_menu_$ i n i t 1 

cal 1 f t_menu_$ini t2 (usage_mode,user_window_l ines,user_window_columns, 

user_wi ndow_id,code) 
! Calling f t_menu_$ ini t MUST 
! be the first call to ft_menu_ in the program. 

if (code .eq. zero) go to 5 

call com_err_ (code, ME, " (calling f t_menu_$i ni t2) ") 

print, "Unable to set up the appropriate environment for the application." 

go to 999 

c The following calls to cv_error_$name are used retrieve and store 
c the error codes associated with certain errors of interest returned 
c by calls to the menu manager or the system. 

5 call cv_error_$name ("error_table_$bad_arg", bad_arg, code) 
if (code .eq. zero) go to 10 

call com_err_ (code, ME, "error_table_$bad_arg") 

go to 999 
10 call cv_error_$name ("menu_et_$too_few_keys", too_few_keys,code) 

if (code .eq. zero) go to 20 

call com_err_ (code, ME, "menu_et_$too_few_keys") 

go to 999 
20 call cv_error_$name ("menu_et_$keys_not_unique", keys_not_unique, code) 

if (code .eq. zero) go to 40 

call com_err_ (code, ME, !! menu_et_$keys_not_unique !! ) 

go to 999 

kO call ft_menu_$create (choices, headers, trai lers,pad_char,menu_format, 

6 keys, menu_needs,menu_id, code) 

c This call creates the menu object and returns the menu object identifier, 



8-17 CP51-02 



ft_window_ ft_window. 



if (code .eq. zero) go to hS 

call com_err_ (code, ME, " (calling f t_menu_$ceate) ") 

print, "The menu could not be created." 

go to 999 

c The created menu is now stored for future use. 

45 dir_name = ">udd>m>ri" ! pathname of directory 

entry_name = "menus_seg" ! entry name of "value" segment 

menu_name = "f t_read_mai l_menu" ! name of menu 

create_seg = 1 ! create "value" seg if it does not already exist. 

call f t_menu_$store (dir_name, entry_name, menu_name, 

create_seg, menu_id, code) 
if (code .eq. zero) go to 50 

call com_err_ (code, ME, " (calling ft_menu_$ store) ") 

print, "The menu could not be stored." 

go to 999 
50 window_id = 

call ft_menu_$di splay (window_id,menu_id,code) ! This call displays 

! the menu in its own window at top of screen. Since the usagejnode 

! was set to 0, the program does not have to create the window 

! before calling ft_menu_$di splay. The window_id argument is ignored. 

if (code .eq. zero) go to 60 

call com_err_ (code, ME, " (calling ft_menu_$di splay) ") 

print, "The menu could not be displayed." 

go to 999 

60 function_key_info = "q" ! Defines the function key requirements, i.e, 

! if the terminal has function key 1 (Fl) then Fl will be used 
! to "quit", otherwise "esc_q" will be used to "quit". 

61 cal 1 f t_menu_$get_choice (window_id,menu_id,function_key_info,f keys, 
&' select ion, code) 

c This call accepts the user input from the menu. On return, the variable 

c "selection" will contain a number (1, 2, 3 » or k) representing the option 

c chosen by user. 

c Note: if the user entered anything other than 1 or 2 or 3 or k 

c the terminal "beeped", and the user input was ignored. 

c Since usage mode is 0, the window_id argument is ignored. 

if (code .eq. zero) go to 90 

if (code .ne. too_f ew_keys) go to 70 

call com_err_ (0, ME, "Number of keys less than number of options.") 

go to 999 
70 if (code .ne. keys_not_uni.que) go to 80 

call com_err_ (0, ME, "Option keys not unique.") 
go to 999 

8-18 CP51-02 



ft window ft_window_ 



80 call com_err_ (code, ME, " (calling f t_menu_$get_choice) 
An internal programming error has occurred,") 

go to 999 
90 if (fkeys .eq. zero) go to 110 

if (fkeys .eq. 1) go to TOO 

print, "An internal program error has occurred. Quitting." 

go to 999 
100 if (selection .ne. 1) go to 6 1 

print, "You entered ""FT"' or ""esc q"". Quitting." 

go to 999 
110 print 103, selection 
103 format ("You selected option "il) 

go to 50 

999 call ft_menu_$ terminate () 
return 
end 



EXAMPLE 2: 

In this example, FORTRAN interfaces with the Multics menu manager and the Multics 
window manager via the ft_menu_ and ft_window_ subroutines. 

subroutine testcase2 () 

% include ft_menu_dcls 

external f t_menu_$ini tl (descriptors) 

external f t_menu_$ i ni t2 (descr iptors) 

external f t_window_$clear_window (descriptors) 

character*9 choices_one (2) 

character^ 1 choices_three(*j) 

character*21 headers (1) 

character*^ trailers (1) 

character*l keys (6) 

character*l68 dir_name 

character*32 entry_name 

character*32 menu_name 

character*! 2 function_key_info 

character*32 match_string 

character*32 names_array (10) 

character *$2 switch_name 

character*9 ME 

integer create_seg 

integer no_of_matches 

integer window_idl 

integer window_id2 

integer fkeys 

integer selection 

integer usage_mode 
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integer 
integer 
integer 
integer 
integer 
i nteger 
integer 
integer 
integer 
integer 



menu_f ormat (6) 

menu_needs_one (3) 

menu_needs_two (3) 

menu_needs_three (3) 

cur r_w i ndow_ i d 

menu_idl 

menu_id2 

menu_id3 

code 

zero 



external com_err_ (descriptors) 



integer 
i nteger 
integer 



bad_window_id 
nonex i s ten t_w i ndow 
insuff room for window 



ME = "testcase2" 
zero = 

choices_one (1) = 
choices_one (2) = 
choices_three (1) 
choices_three (2) 
choices_three (3) 
choices_three (4) 
trailers(l)= "Fl 
"1" 
"2" 

II 311 
llj^ll 

"5" 

"6" 

_ ■ ■ • ■ 



"Read Mail" 
"Send Mail" 
= "Send New Messsage" 
= "Send Deferred Mjessage" 
= "Print Sent Message" 
= "Save Sent Message" 
(or esc-q) = quit ; F2 (or esc-f) 



= f i rst menu" 



keys(l) 

keys (2) 

keys (3) 

k"eys (it) 

keys (5) 

keys (6) 

pad_char = 

menu_f ormat (menu_vers ion) = 1 

menu_format (max_width) = 79 

menu_f ormat (max_height) = 8 

menu_f ormat (no_of_columns) = 2 

menu_format (center_headers) = 1 

menu_f ormat (center_trai lers) = 1 

code = 

call f t_menu_$ini tl () 

usage_mode = 1 Window management will be done by user 
cal 1 f t_menu_$ini t2 (usage_mode,user_window_l ines,user_window_columns, 
user_window_id,code) Calling f t_menu_$ ini t MUST be the 

first call to ft_menu_ in the program. 
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if (code .eq. 0) go to 5 

call com_err_ (code, HE, " (calling f t_menu_$init) ") 
print, "Unable to set up the appropriate environment for the 
6 application." 

go to 999 

c The following calls to cv_error_$name are used retrieve and store 
c the error codes associated with certain errors of interest returned 
c by calls to the menu manager or the system. 

5 call cv_error_$name ("video_et_$bad_window_id", bad_window_id, code) 
if (code .eq. zero) go to 10 

call com_err_ (code, ME, "video_et_$bad_window_id") 

go to 999 
10 call cv_error_$name ("video_et_$nonexistent_window", 

nonex i s ten t_w i ndow , code) 

if (code .eq. zero) go to 20 

call com_err_ (code, ME, "video_et_$nonexistent_window") 

go to 999 
20 call cv_error_$name ("video_et_$insuff_room_for_window", 

6 insuff_room_for_window, code) 
if (code .eq. zero) go to 40 

call com_err_ (code, ME, "video_et_$insuff_room_for_window") 
go to 999 

c Create first menu 

kO headers (1) = "MULTICS MAIL" 

cal 1 f t_menu_$create (choices_one, headers, trai lers,pad_char ,menu_format, 
& keys,menu_needs_one,menu_idl , code) 

c This call creates the menu object and returns the menu object identifier, 
c This menu is referenced by menu_idl. 

if (code .eq. 0) go to 41 

call com_err_ (code, ME, " (calling f t_menu_$ceate) ") 

print, "The first menu could not be created." 

go to 999 

c For the second menu use a menu object which was stored in a "value" seg. 
c First determine if menu object exists. 

k] dir_name = ">udd>m>ri" 

entry_name = "menus_seg" 

match_string = "f t_read_mai l_menu" 

cal 1 f t_menu_$l ist (di r_name,entry_name,match_str ing,no_of_matches, 
& names_ar ray, code) 

if (code .eq. zero) go to k2 

call com_err_ (code, ME, " (calling f t_menu_$l ist) ") 

go to 999 
k2 if (no_of_matches .eq. zero) then 
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print, "Stored menu not found." 

go to 999 

else 

if (no_of_matches .eq. 1) go to hi 

print, "Internal error. Quitting." 

go to 999 

end i f 

c Retrieve stored menu. 

U3 menu_name = "f t_read_mai l_menu" 

call ft_menu_$ retrieve (dir_name,entry_name,menu_name,menu_id2,code) 

if (code .eq. zero) go to kk 

call com_err_ (code, ME, " (calling f t_menu_$ retrieve) ") 

go to 999 

c Get attributes of retrieved menu. 

kk call f t_menu_$descr ibe (menu_id2,menu_needs_two,code) 

if (code .eq. zero) go to US 

call com_err_ (code, ME, " (calling f t_menu_$descr ibe) ") 
go to 999 

c Create third menu 

2,5 headers (1) = "SEND MAIL" 

call ft_menu_$create (choices_three, headers, trai lers,pad_char, 
6 menu_f ormat , keys ,menu_needs_three ,menu_i d3 , code) 

if (code .eq. 0) go to 50 

call com_err_ (code, ME, " (calling f t_menu_$ceate) ") 

print, "The third menu could not be created." 

go to 999 

50 curr_window_id = -1 "-1" indicates that there is no current menu 

being displayed; otherwise, curr_window_id 
contains the menu window id 

52 call changejnenu (user_wi ndow_id,curr_wi ndow_id,menu_idl ,menu_needs_one, 
& user_window_l ines,window_idl .code) 

if (code) 51.53,51 . in 

51 call com_err_ (code,"change_menu"," I nternal error while changing menus. ; 

go to 999 , 

53 call ft_window_$clear_window (user_window_id, code) 

60 call get_choice (menu_idl ,window_idl ,f keys, selection, code) 

c This call accepts the user input from the menu. On return, the variable 

c "selection" will contain a number (0, 1, 2) representing the option or 

c the function key (or its equivalent escape sequence) entered by the user, 

c If fkeys = 1 then the user entered Fl or F2 (or esc-q or esc-f ) : 
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c if Fl (or esc-q) was entered, then selection = 

c if F2 (or esc-f) was entered, then selection = 1 

c If fkeys = then the user selected option: 

c if first option was chosen, then selection = 1 

c if second option was chosen, then selection = 2 

c Note: if the user entered anything other than Fl or F2 or 1 or 2 

c the terminal "beeped", and the user input was ignored. 

if (code .eq. zero) go to 70 

call com_err_ (0, "get_choice", "Internal program error 

while getting user choice") 
go to 999 
70 if (fkeys .eq. zero) go to 90 user selected an option 
if (fkeys .eq. 1) then 
go to 80 user entered function key 
else Something is wrong 

print, "An internal program error has occurred. Quitting." 
go to 999 
end i f 

80 go to (81,82), selection 

call com_err_ (code, ME, "An internal program has occurred. Quitting.") 
go to 999 

81 print, "Exiting" (user has entered Fl or esc-q. Wants to exit) 
go to 999 

82 print, "You already are in the first menu." User want to go to 

first menu 

go to 60 
90 go to (100,170), selection Display either "Read Mail" or "Send Mail" 

menu 

call com_err_ (code, ME, "Internal program error. Quitting.") 

go to 999 
100 call changejnenu (user_window_id,window_idl ,menu_id2,menu_needs_two, 
& user_window_l ines, window_id2, code) 

if (code .eq. zero) go to 110 

call com_err_ (code, "changejnenu", "Internal error occurred 

while switching menus") 

go to 999 
110 call get_choice (menu_id2, window_id2, fkeys, selection, code) 

if (code .ne. zero) then 

call com_err_ (code, "get_choice", "Internal error 

while getting user choice"). 

go to 999 

end i f 

go to (160,150) , fkeys + 1 

call com_err_ (code, ME, "Internal program error. Quitting.") 

go to 999 

150 go to (151,152), selection user entered function key 
go to 110 

151 print, "Exiting at your request" 
go to 999 

152 curr_window_id = window_id2 
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go to 52 
160 print 300, selection 

300 format ("You selected option "il) 
go to 110 

c User chose "Send Mail" option 

170 call changejnenu (user_window_id, window_idl ,menu_id3»menu_needs_three, 
& user_wi ndow_l ines,window_id2,code) 

if (code) 171,180,171 

171 call com_err_ (code, "change_menu" , "Internal error 

while changing menus") 

go to 999 

180 call get_choice (menu_id3,window_id2,f keys, selection, code) 
if (code) 181,190,181 

181 call com_err_ (code, "get_choice", "Internal error 

while getting user choice") 
go to 999 
190 go to (210,200), fkeys + 1 

pr int, ." Internal error. Quitting" 
go to 999 

200 go to (201,202), selection 
go to 180 

201 print, "Exiting at your request." 
go to 888 

202 curr_window_id = window_id2 
go to 52 

210 print 301, selection 

301 format ("You selected option "il) 
go to 180 

c Delete second menu from the value seg. 

888 call f t_menu_$delete (di r_name,entry_name,menu_name,code) 

if (code .eq. zero) go to 999 

print, "Menu could not be deleted from value segment." 
999 call f t_menu_$terminate () 

return 

end 
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subroutine get_choice (menu_id,window_id, fkeys, selection, code) 

external f t_menu_$get_choice (descriptors) 

characters function_key_info 

integer fkeys 

integer selection 

integer menu_id 

integer window_id 

integer code 

code = 

function_key_info = "qf" Defines the function key requirements, i.e, 
if the terminal has function keys 1 and 2 (Fl and F2) then Fl 
will be used to "quit" and F2 to switch to the first menu, 
otherwise "esc_q" will be used to "quit" and "esc-f" to switch 
to the first menu 

ca 1 1 f t_menu_$get_cho i ce (w i ndow_i d , menu_i d , f unc t i on_key_i nf o , fkeys , 
& select ion, code) 

return 
end 

subroutine change_menu (user_window_id,curr_window_id,menu_id,menu_needs, 

user_wi ndow_l ines,window_id,code) 

external f t_window_$change (descriptors) 

external f t_window_$create (descriptors) 

external f t_window_$destroy (descriptors) 

external f t_menu_$di splay (descriptors) 

external com_err_ (descriptors) 

character*32 switch_name 

i nteger menu_needs (3) 

integer user_window_id 

integer user_wi ndow_columns 

i nteger user_wi ndow_l i nes 

integer curr_window_id 

integer menu_id 

integer window_id 

integer code 

integer first_1ine 

integer height 

parameter (1 ines_needed = 1) 
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c Destroy the current menu-window 

if (curr_window_id + 1) 90,100,90 
90 call ft window_$destroy (cur r_window_id, code) 
if (code) "999, 100,999 

c Change the si2e of the user i/o window to accomodate the new menu-window 

100 first_line = 1 + menu_needs (1 ines_needed) 

height = user_window_l i nes - menu_needs (1 ines_needed) 

call ft window_$change (user_window_id,f i rst_l ine, height, code) 

if (code") 999,110,999 

c Create window for new menu 

110 switch_name = "menu_window" 

call ft_window_$create (1 ,menu_needs (1 ines_needed) ,swi tch_name,window_id, 
& code) 

if (code) 999,120,999 

c Display the menu in the menu-window 

120 call ft_menu_$di splay (window_id,menu_id,code) 

999 return 
end 
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This section contains descriptions of the COBOL interface to the menu and video 
software. Two sample COBOL programs are provided that illustrate menu creation using 
automatic window management, and the COBOL video interface capabilities. 

In the COBOL environment, window management can be performed automatically. By 
using the COBOL window management functions cb_menu_$initl, cb_menu_$imt2, an d 
cb_menu_$terminate, applications that do not require sophisticated window management can 
employ automatic window management activity. When using automatic window management, 
your application works in two-window mode: the window in which the menu is displayed and 
the user_i/o window. 

If your application requires greater window management capabilities, the menu interface 
capability lets you build viable menu applications using the cb_window_$create, 
cb_window_$destroy, and cb_window_$change capabilities. 

Of course, COBOL applications can still use command or PL/1 video management 
capabilities. 
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Name: cb menu 

The cb_menu_ subroutine allows a COBOL program to use the Multics menu facility (menu_). 
Through cb_menu_ a COBOL program may create a menu object, display the menu, and get 
a user-entered selection from a menu. Once a menu object has been created, the COBOL 
program can use this menu object by referencing it via a menu-id returned to the caller 
when the menu objeet was created or when a stored menu object was retrieved. 

The functionality available is provided through the various entry points described below. 

Entry: cb menu Screate 

Utilized to create a menu-object. Returns a menu-id which may be subsequently used by 
other entry points. 

USAGE 

declarations: 

01 choices-table. 

02 choices PIC X(nl) OCCURS (ml) TIMES. 
01 headers-table. 

02 headers PIC X (n2) OCCURS (m2) TIMES. 
01 trailers-table. 

02 trailers PIC X (n3) OCCURS (n»3) TIMES. 
01 keys-table. 

02 keys PIC X(l) OCCURS (mk) TIMES. 

01 menu-format. 

02 menu_version USAGE IS C0MP-6 
02 constraints USAGE IS C0MP-6 

03 max-width. 

03 max-height. 
02 no-of -columns USAGE IS C0MP-6. 
02 flags. 

03 center-headers PIC 9(1) . 

03 center-trailers PIC 90) • 
02 pad-char PIC X(l) . 

01 menu-needs USAGE IS C0MP-6. 
02 1 ines-needed. 
02 width-needed. 
02 no-of -opt ions. 

77 menu- id USAGE IS COMP-6. 
77 ret-code USAGE IS COMP-6. 
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call "cb_menu_$create" USING choices-table, headers-table, 

trailers-table, menu-format, keys-table, menu-needs, menu-id, 
ret-code. 

STRUCTURE ELEMENTS 



choices-table 

is a table of elementary data items which are the text of the options that the user 
wishes to display in the menu, nl is the length, in characters, of the longest character 
string comprising the text of an option, ml is the extent of the table, i.e., the number 
of options in the menu being described. This table must be at least of extent 1. 

headers-table 

is a table of elementary data items to be displayed at the top of the menu. (Input) n2 
is the length, in characters, of the longest header specified. m2 is the extent of the 
table, i.e., the number of headers (lines) desired. At least one header must be specified 
(if the first header is set to space(s), no headers will be used). 

trailers-table 

is an table of trailers (displayed immediately below the menu). (Input) n3, m3, are 
analogous to n2, m2 respectively. 

menu-format 

is a group item defining the format of the menu being created. (Input) 
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In the COBOL program the caller is responsible for setting the following elementary data 
items: 



menu-vers ion 

max-width 

max-height 

no-of -columns 

center-headers 
center-trai lers 



the version number of the menu facility, 
(only version 1 is currently defined) 
maximum width of the window on which the 
menu is to be displayed, 
maximum height of window on which the 
menu is to be displayed, 
number of columns to be used to display 
the options. 

or 1 ; = no, 1 = yes. 
or 1 (same as center-headers) 



keys-table 

is a table (maximum value of m4 is 61) that identifies the keystroke to be associated 
with each choice. (Input) This table must be at least as long as the number of choices 
in the menu. Each element in the table must be unique. 

menu-needs 

a group item that contains menu related information on successful execution of call. 

(Output) 

Returned information: 

lines-needed the number of lines required 

to display the menu, 
width-needed the number of columns needed 

to display the menu, 
no-of -opt ions the number of options defined 

in the menu. 



menu-id 

the menu-object identifier (i.c, it is the menu object "pointer".) (Output) It must not be 
altered in any way by the application program. 

ret-code 

return code. (Output) (See Appendix B.) 



9-4 



CP51-02 



cbmenu cb_menu_ 



Entry: cb menu_$delete 

Deletes a menu object from a given value segment. 

USAGE 

declarations: 

77 dir-name PiC X (168) . 

77 entry-name PIC X (32) . 

77 name-of-menu PIC X (32) . 

77 ret-code USAGE IS COMP-6. 



call "cb_menu_$delete" USING dir-name, entry-name, name-of-menu, 
ret-code. 

STRUCTURE ELEMENTS 



dir-name 

pathname of the directory containing the menu object (Input) 

entry-name 

entry name of value segment containing the menu object. (Input) The suffix "value" need 
not be specified. 

name-of-menu 

name used to identify the menu object when the menu object was stored. {Input) 

ret-code 

return code. (Output) (See Appendix B.) 

Entry: cb menu_$describe 

Returns information about a menu object It returns the number of options in the menu, the 
number of lines and number of columns required to display the menu. It is primarily used 
to determine if the menu can be displayed in a given window. 
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USAGE 

declarations: 

01 menu-needs USAGE IS COMP-6. 
02 1 ines-needed. 
02 width-needed. 
02 no-of -opt ions. 

77 menu-id USAGE IS C0MP-6. 

77 ret-code USAGE IS C0MP-6. 

call "cb_menu_$descr ibe" USING menu-id, menu-needs, ret-code. 

STRUCTURE ELEMENTS 



menu-id 

the menu identifier returned by cb_menu_$create (or cb_menu_$retrieve in cases where 
the menu object has been stored). (Input) 

menu-needs 

a group item that contains menu related information on successful execution of call. 
(Output) 

Returned information: 

lines-needed the number of lines needed to 

display the menu, 
width-needed the number of columns needed 

to display the menu, 
no-of-option the number of options defined 

in the menu. 



ret-code 

return code. (Output) (See Appendix B.) 

Entry: cb menu Sdestroy 

Used to free storage of a menu (not to be confused with cb_menu_$delete, which is used to 
delete the menu object from a value segment). Destroying the menu has no effect on the 
screen contents. 
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USAGE 

declarations: 

77 menu- id USAGE IS COMP-6. 
77 ret-code USAGE IS COMP-6. 

call "cb_menu_$destroy" USING menu-id, ret-code. 

STRUCTURE ELEMENTS 

menu-id 

menu identifier returned by cb_menu_$create or cb_menu_$retrieve. (Input/Output) (If 
usage-mode is (see cb_menu_$init2) this operand will be ignored.) Set to an invalid 
value on return to prevent the old menu-id from being accidentally used. 

ret-code 

return code. (Output) (See Appendix R) 

Entry: cb_menu {display 

Invoked to display a menu in a given window. 

USAGE 

declarations: 

77 window-- id USAGE IS COMP-6. 

77 menu- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_menu_$d i splay" USING window-id, menu-id, ret-code. 

STRUCTURE ELEMENTS 

window-id 

a window identifier returned by cb_window_$create entry point (Input) If usage-mode = 
this operand will be ignored (see cb_menu_$init2). 

menu-id 

menu identifier returned when the menu object was created or retrieved. (Input) 

ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb menu_$get_choice 

Returns the choice made by the user, i.e., a number representing either the menu item chosen 
or the function key (or its equivalent escape sequence) entered. 

USAGE 



declarations: 






77 


function-key- 


info 


PIC X(nl) . 


77 


w i ndow- i d 




USAGE IS COMP-6. 


77 


menu- i d 




USAGE IS COMP-6. 


77 


fkeys 




USAGE IS COMP-6. 


77 


selection 




USAGE IS COMP-6. 


77 


ret-code 




USAGE IS COMP-6. 



call "cb_menu_$get_choice" USING window- id, menu-id, function-key-info, 
fkeys, selection, ret-code. 

STRUCTURE ELEMENTS 

window-id 

a window identifier returned by the cb_window_$create entry point (Input) If 
usage-mode = this operand will be ignored (see cb_menu_$init2). 

menu-id 

menu identifier returned by cb_menu_$create or cb_menu_$retrive. (Input) 

function-key-info 

a character elementary data item (nl as required) used to specify the role of function 
keys (if they exist for the terminal being used) or an equivalent set of escape sequences 
if the terminal does not have function keys or not the function keys required by the 
application. (Input) The objective is to let the application use the terminal's function 
keys if possible, else specify key sequences to be used to simulate function keys. Each 
character in the string corresponds to one function key. If the character is a space, then 
it is not relevant if the corresponding function key exists or not If the character is not 
a space, that character will be used to simulate a function key if the terminal does not 
have function keys. If the terminal does not have a function key for every non-space 
character in the string, then function keys will be simulated. Thus, the string " ?p q" 
means that the caller does not care whether the terminal has function key or 3, but 
the caller does wish to use function keys 1,2, and 4. If any of these 3 function keys is 
not present on the terminal, then esc-? will substitute for Fl. esc-p will substitute for 
F2, and esc-q will substitute for F4. 

fkevs 

fkeys = 1 user entered a function key or escape sequence fkeys = user selected an 

option (Output) 
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selection 

is a number representing the choice made by the user. (Output) If the user has chosen 
an option, it is a number between 1 and the highest defined option. If the user has 
entered a function key, or escape sequence simulating a function key, it is the number 
associated with the function key. 

ret-code 

return code. (Output) (See Appendix B.) 

Entries: cb_menu Sinitl, cb_menu $init2 

These must be the first calls made to the menu manager. They set up the necessary 
environment for the menu application and return information concerning the user I/O 
window. 

USAGE 

declarations: 

inter code 
integer usage-mode 

caii cb_menu_$ i n i t 1 

call cb_menu_$ini t2 (usage-mode, user-window-1 ines, user-window-columns, 
user-window-id, ret-code) 

STRUCTURE ELEMENTS 



usage-mode 

usage-mode = means that the caller does not wish to do any explicit window 
management (Input) When he/she wishes to display a menu, the window required will 
be automatically created. This means that the application will operate in a two window 
mode, the window containing the menu, and the user_io window. Both windows will be 
managed automatically for the user. If the user specifies this mode, all calls to the 
cb_window_ subroutine will be ignored and will return an appropriate error code. See 
Error Code Handling, below. All calls to the cb_menu_ subroutine that require a window 
identifier will ignore the user provided window-id. 

usage-mode = 1 means that the user wishes to define the number and characteristics of 
the windows to be used in the application. Thus, calls to cb_window_ will be supported 
and, for the entry points of cb_menu_ that require a window identifier, the caller must 
use a legal window-id (returned by cb_window_$create). 

user-window-lines 

the number of physical lines (rows) of the user i/o window when cb_menu_$init is 
called (which must be the first cb_menu_ call in the application.) Undefined if 
usage-mode = 0. (Output) 
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user-window-columns 

the number of columns of the user i/o window at time that cb_menu_$init is called (see 
immediately above). (Output) Undefined if usage-mode = 0. 

user-window-id 

window identifier of the user i/o window. (Output) Undefined if usage-mode = 0. 

ret-code 

return code. (Output) (See Appendix B.) 

Entry: cb_menu_$list 

Used to list the menu object(s), stored in value segment The menu objects selected are those 
that match the string input by the caller. 

USAGE 

declarations: 

01 matched-names. 

02 no-of -matches USAGE IS C0MP-6. 

02 menu-names PIC X (32) OCCURS (ml) TIMES. 

77 dir-name PIC X(l68) . 

77 entry-name PIC X (32) . 

77 match-string PIC X (32) . 

77 ret-code USAGE IS C0MP-6, 

call "cb_menu_$l ist" USING dir-name, entry-name, match-string, 
matched-names, ret-code. 

STRUCTURE ELEMENTS 



dir-name 

pathname of directory containing the menu object. (Input) 

entry-name 

entry name of value segment containing the menu object (Input) The suffix "value" need 
not be specified. 

match-string 

a character elementary data item that is to be used as the selection criteria for 
determining what menu object, if any, is contained in the specified value segment that 
match (or contain) this string. (Input) 

no-of -matches 

the number of matches found. (Output) If none, then it is 0. 
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menu-names 

On return, contains the names of all menu objects, in the specified value segnent, that 

match the character string match-string. (Output) Note, if ml is not large enough to 

contain all the names, only ml names will be returned. 

ret-code 

return code. (Output) (See Appendix B.) 

Entry: cb_menu Sretrieve 

Used to retrieve a menu object previously stored via the cb_menu_$store subroutine. 

USAGE 

declarations: 

77 dir-name PIC X(l68) . 

77 entry-name PIC X (32). 

77 name-of-menu. PIC X (32) . 

77 menu- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_menu_$retrieve" USING dir-name, entry-name, name-of-menu, 
menu-id, ret-code. 

STRUCTURE ELEMENTS 

dir-name 

pathname of the directory containing the menu object (Input) 

entry-name 

entry name of value segment containing menu object (Input) The suffix "value" need not 
be specified. 

name-of-menu 

name of the menu object used when the object was stored. (Input) 

menu-id 

is the menu id returned by the call. (Output) 

ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb menu_$store 

Used to store a menu object in a specified value segment 

USAGE 

declarations: 

77 dir-name PIC X(l68) . 

77 entry-name PIC X (32). 

77 name-of-menu PIC X (32) . 

77 create-seg USAGE IS COMP-6. 

77 menu- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_menu_$store" USING dir-name, entry-name, name-of-menu, 
create-seg, menu-id, ret-code. 

STRUCTURE ELEMENTS 

dir-name 

pathname of directory into which the menu object is to be placed. (Input) 

entry-name 

entry name of value segment into which menu object is to be placed. (Input) The suffix 
"value" need not be specified. 



name-of-menu 

is the name to be assigned to the stored menu object (Input) 

create-seg 

create-seg = means do not store if value segment identified by entry-name does not 
already exist (Input) create-seg = 1 means create value segment, if it does not already 
exist, and store menu object in it 

menu-id 

is the menu object identifier returned by cb_menu_$ereate or eb_menu_$retrieve. (Input) 

ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb__menu Sterminate 

Must be the last call to the menu manager in the menu application. 

USAGE 

declarations: none 

call "cb_menu_$terminate". 

STRUCTURE ELEMENTS 
There are no arguments. 
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Name: cb window__ 

This is the basic video interface subroutine to be used by COBOL to create/destroy/change 
windows. (If usage-mode = (see cb_menu_$init2) this subroutine should not be called.) 

Its facilities are available through the following entry points. 

Entry: cb window $change 

This entry points provides a facility for changing the size of an existing window. The size of 
a window can always be "shrunk", however it can be increased only it does not overlap with 
another defined window. (If usage-mode = (see cb_menu_$init2) this entry point should not 
be called.) 

USAGE 

declarations: 

77 window- id USAGE IS COMP-6. 

77 first- line USAGE IS COMP-6. 

77 height USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_window_$change" USING window- id, first-line, height, 
ret-code. 



STRUCTURE ELEMENTS 



window-id 

window identifier returned by cb_window_$create. (Input) 

first-line 

new first line number for the window being changed. (Input) A positive value. 

height 

new height for the window being changed. (Input) A positive value, 

ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb_window_$clear_window 

Used to clear a specified window. 

USAGE 

declarations: 

77 window-id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_window_$clear_window" USING window-id, ret-code. 

STRUCTURE ELEMENTS 

window-id 

the window identifier (returned by cb_window_$create) of the window to be cleared. 
(Input) 

ret-code 

return code. (Output) (See Appendix B.) 

Entry: cb_window__$create 

This entry is used to create a new window on the terminal screen. (If usage-mode = (see 
cb_menu_$init2) this entry point should not be called.) 

USAGE 

declarations: 

77 switch-name PIC X (32). 

77 first-line USAGE IS COMP-6. 

77 height USAGE IS COMP-6. 

77 window- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_window_$create" USING first-line, height, switch-name, 
window- id, ret-code. 

STRUCTURE ELEMENTS 

first-line 

is the line number where the window is to start (Input) 

height 

the number of lines used by the window, i.e., its height. (Input) 
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switch-name 

the name that the caller wishes to associate with the switch. (Input) 

window-id 

the returned id of the window just created. (Output) It must not be altered in any way 
by the application program. 

ret-code 

return code. (Output) (See Appendix B.) 

Entry: cb window Sdestroy 

Used to destroy a previously created window. (If usage-mode = (see cb_menu_$init2) this 
entry point should not be called.) 

USAGE 

declarations: 

77 window- id USAGE IS C0ttP-6. 
77 ret-code USAGE IS COHP-6. 

call "cb_window_$destroy" USING window-id, ret-code. 
STRUCTURE ELEMENTS 



window-id 

window identifier (returned by the cb_window_$create). (Input/Output) It is reset to an 
illegal value by this call. 

ret-code 

return code. (Output) (See Appendix B.) 

COBOL MENU APPLICATION EXAMPLES 

In the following two COBOL examples, a "Message" menu application is created that allows 
you to display, print, discard, or forward messages. Example 1 is a simple COBOL program 
that interfaces with the Multics menu manager via the cb_menu_ routine. Note in example 1 
that window management functions are called automatically through arguments in the 
ft_menu_$init2 subroutine. 

Example 2 is a COBOL program that interfaces with the Multics menu manager through the 
cb_menu_routine; in example 2, however, window management functions are performed by the 
cb_window_ routine. 
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EXAMPLE 1: 

In this example, all window management is done automatically. 

* A simple COBOL program interfacing with the Multics * 

* menu manager via the cb_menu_ routine. * 

CONTROL DIVISION. 

DEFAULT GENERATE AGGREGATE DESCRIPTORS. 

IDENTIFICATION DIVISION. 

PROGRAM- I D . 
cbtestl . 



AUTHOR. 



R. I 



ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. 
Mul tics. 

OBJECT-COMPUTER. 
Multics. 

DATA DIVISION. 
WORKING-STORAGE SECTION. 



X (15) OCCURS 6 TIMES. 
X(lit) OCCURS 1 TIMES. 



01 choices-table. 

02 choices PIC 
01 headers-table. 

02 headers PIC 
01 trailers-table. 
02 trailers PIC X(32) OCCURS 1 TIMES. 

01 keys-table. 
02 keys PIC X(l) OCCURS 6 TIMES. 

01 menu-format. 

02 menu-version USAGE IS C0MP-6 VALUE 1 

02 constraints USAGE IS COMP-bV 

03 max-width VALUE 79- 

03 max-height VALUE 10. 

02 no-of -columns USAGE IS C0MP-6 VALUE 2 
02 flags. 

03 center-headers PIC 9(1) VALUE 1 

03 center-trailer PIC 9(1) VALUE 1 
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02 padder PIC X(l) VALUE "-", 



01 menu-needs 
02 lines-needed. 
02 width-needed. 
02 no-of -opt ions. 



USAGE IS C0MP-6. 



77 dir-name 


PIC X (168) . 


77 entry-name 


PIC X(32) 


. 


77 menu-name 


PIC X(32) 


. 


77 function-key-info 


PIC X(l) 


VALUE "q". 


77 me 


PIC x(7) 


VALUE "cbtestl". 


77 menu- id 








USAGE IS C0MP- 


•6. 






77 ret-code 


USAGE 


IS 


C0MP-6. 


77 window- id 


USAGE 


IS 


C0MP-6. 


77 fkeys 


USAGE 


IS 


C0MP-6. 


77 option 


USAGE 


IS 


C0MP-6. 


77 easy-mode 


USAGE 


IS 


C0MP-6 VALUE zer 


77 user-wi ndow-1 ines 


USAGE 


IS 


C0MP-6. 


77 user-wi ndow-columns 


USAGE 


IS 


C0MP-6. 


77 user-window- id 


USAGE 


IS 


C0MP-6. 


77 create-seg 


USAGE 


IS 


C0MP-6. 



77 keys-not-unique 
77 too-few-keys 
77 bad-arg 



USAGE IS C0MP-6, 
USAGE IS C0MP-6. 
USAGE IS C0MP-6. 



PROCEDURE DIVISION. 

* The call to the cv_error_$name are used to collect the code for 

* certain error messages that are of interest this application. 

* Once these codes are retrieved the occurrence of that error can 

* be easily tested for. 

START- IT. 

CALL "cb_menu_$initl". 
CALL "cb_menu_$ini t2" USING easy-mode, user-wi ndow-1 ines, 
user-window-columns, user-wi ndow- id, ret-code. 

* The calls to cb_menu_$ini tl & 2 MUST be the first calls to cb_menu_ 

* They set up the appropriate environment for the menu application. 

IF ret-code EQUAL TO zero GO TO NEXT-ERR-CODE . 
CALL "com_err_" USING ret-code, me, "Internal error. 

Could not set up appropriate environment.". 
GO TO STOP- IT. 

CALL "cv_error_$name" USING "menu_et_$keys_not_unique", 
keys-not-unique, ret-code. 
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call "ioa_" USING "Error code for keys-not-unique = ^d", keys-not-unique. 

iF ret-code EQUAL TO zero GO TO NEXT-ERR-CQDE. 

CALL "com_err_" USING ret-code, me, " (calling cv error_$name) ". 

GO TO STOP- IT. 

NEXT-ERR-CODE. 
CALL "cv_error_$name" USING "error table_$bad_arg", bad-arg, ret-code= 
IF ret-code EQUAL TO zero GO TO LAST-ERR-CODE. 

CALL "com_err_" USING ret-code, me , " (calling cv_error_$name) ". 
GO TO STOP- IT. 

LAST-ERR-CODE. 
CALL "cv_error_$name" USING "menu_et_$too_few_keys", too-few-keys, 

ret-code. 
IF ret-code EQUAL TO zero GO TO SET-UP. 

CALL "com_err_" USING ret-code, me, " (calling cv_error_$name) ". 
GO TO STOP- IT. 

SET-UP. 

MOVE 1 TO menu-version. 
MOVE "Display Message" TO choices(l). 
MOVE "Print Message" TO choices (2). 
MOVE "Discard Message" TO choices (3). 

MOVE "Forward Message" TO choices (it). 
MOVE "Reply Message" TO choices (5). 

MOVE "List Messages" TO choices (6). 

MOVE " MULTICS MAIL " TO headers (1). 

MOVE "Press Fl or enter esc-q to quit" TO trailers (1). 

MOVE "1" TO keys(l) . 

MOVE "2" TO keys (2) . 
MOVE "3" TO keys (3) . 

MOVE "k" TO keys (k) . 
MOVE "5" TO keys (5) . 
MOVE "6" TO keys (6) . 



MENU-CREATE. 

DISPLAY choices-table. 
DISPLAY menu-version. 
CALL "cb_menu_$create" USING choices-table, headers-table, 

trailers-table, menu-format, keys-table, menu-needs, 

menu- id, ret-code. 

* This call creates a menu object and return the menu object 

* identifier. This menu object is referenced as "menu- id". 
IF ret-code EQUAL TO zero GO TO STORE-MENU. 

CALL "com_err_" USING ret-code, me, " (calling cb_menu_$create) ". 
GO TO STOP- IT. 
STORE-MENU. 
MOVE ">udd>m>ri" TO dir-name. 
MOVE "menus_seg" TO entry-name. 
MOVE "cb_read_mai l_menu" TO menu-name. 
MOVE 1 TO create-seg. 
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CALL "cb_menu_$store" USING dir-name, entry-name, menu-name, 

create-seg, menu-id, ret-code. 
IF ret-code EQUAL TO zero GO TO DISPLAY-MENU. 

CALL "com_err_" USING ret-code, me, "(calling cb_menu_$ store) ". 
GO TO STOP- IT. 

DISPLAY-MENU. 
CALL "cb_menu_$di splay" USING window- id, menu- id, ret-code. 

* This call displays the menu in its own window at top of screen. 

* Since the usage-mode was set to 0, the program does not have to 

* create the window before calling cb_menu_$di splay. 

* The window- id argument is ignored. 

IF ret-code EQUAL TO zero GO TO GET-CHOICE. 

CALL "com_err_" USING ret-code, me, "Internal error. 

Menu~could not be displayed." 
GO TO STOP- IT. 
GET-CHOICE. 

* Defines the function key requirements, i.e., 

* if the terminal has function key 1 (Fl) then Fl will be used 

* to "quit", otherwise "esc q" will be used to "quit". 

CALL "cb_menu_$get_choice" USING window-id, menu-id, 

functTon-key-info, fkeys, option, ret-code. 
IF ret-code EQUAL TO zero GO TO TEST-FKEY. 
CALL "com_err_" USING ret-code, me, "Internal error. While getting 

user's choice.". 
GO TO STOP- IT. 
TEST-FKEY. 
IF fkeys EQUAL TO 1 

CALL "ioa_" USING "Exiting at your request." 
GO TO STOP- IT 
ELSE 

CALL "ioa_" USING "You chose option ~d.", option 
GO TO GET-CHOICE. 

STOP- IT. 
CALL "cb menu_$terminate". 

* cb_menu_$terminate MUST be the last call to cb_menu_ in the 

ft application. It terminates the environment set up cb_menu_$ i n i t . 

EXIT PROGRAM. 



9-20 CP51-02 



cb_window_ cb window 



EXAMPLE 2: 

In this example, COBOL interfaces with the Multics menu manager and the Multics window 
manager via the cb_menu_ and cb_window_ subroutines. 

* A simple COBOL program interfacing with the Multics * 

* menu manager and window manager via the cb_menu_ and * 

* cb_window_ routines, respectively. * 

CONTROL DIVISION. 

DEFAULT GENERATE AGGREGATE DESCRIPTORS. 

IDENTIFICATION DIVISION. 

PROGRAM- ID. 
cbtest2. 

AUTHOR. 
R. I . 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. 
Mul tics. 

OBJECT-COMPUTER. 
Multics. 

DATA DIVISION. 
WORKING-STORAGE SECTION. 

01 choices-tablel . 

02' choices 1 PIC X (9) OCCURS 2 TIMES. 
01 choices-table2. 

02 choices2 PIC X (15) OCCURS 6 TIMES. 
01 choices-table3. 

02 choices3 PIC X(21) OCCURS k TIMES. 
01 headers-table. 

02 headers PIC X (23) OCCURS 1 TIMES. 
01 trailers-table. 
02 trailers PIC X (52) OCCURS 1 TIMES. 

01 keys-table. 
02 keys PIC X(l) OCCURS 6 TIMES. 

01 menu-format. 

02 menu-version USAGE IS C0MP-6 VALUE 1. 

02 constraints USAGE IS C0MP-6. 

03 max-width VALUE 80. 
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03 max-height VALUE 
02 no-of -columns USAGE 
02 flags. 

03 center-headers 
03 center-trai ler 

02 padder PIC 

01 menu-needs 1 
02 1 ines-neededl . 
02 width-needed 1 . 
02 no-of-optionsl . 

01 menu-needs2 
02 1 ines-needed2. 
02 width-needed2. 
02 no-of-opt i ons2 . 

01 menu-needs3 
02 1 ines-needed3> 
02 width-needed 3> 
02 no-of-opt ions3- 



10. 

IS C0MP- 



6 VALUE 2. 



PIC 9(1) VALUE 1 
PIC 9(1) VALUE 1 
X(l) VALUE "-". 

USAGE IS COMP-6. 



USAGE IS COMP-6. 



USAGE IS COMP-6. 



77 dir-name 




PIC X(l68) . 


77 entry-name 




PIC X(32) 


. 


77 menu-name 




PIC X(32) 


. 


77 function-key 


-info 


PIC X(2) 


VALUE "qf". 


77 me 




PIC X(7) 


VALUE "cbtest2" 


77 switch-name 




PIC X(32) 


• 


77 1 i nes-needed 




USAGE 


IS 


COMP-6. 


77 f irst-1 ine 




USAGE 


IS 


COMP-6. 


77 height 




USAGE 


IS 


COMP-6. 


77 menu- id 




USAGE 


IS 


COMP-6. 


77 menu- id! 




USAGE 


IS 


COMP-6, 


77 menu-id2 




USAGE 


IS 


COMP-6. 


77 menu-id3 




USAGE 


IS 


COMP-6. 


77 ret-code 




USAGE 


IS 


C0MP-6. 


77 curr-window- 


id 


USAGE 


iS 


COMP-6. 


77 window- id 




USAGE 


IS 


COMP-6. 


77 window- idl 




USAGE 


IS 


COMP-6. 


77 window-id2 




USAGE 


IS 


COMP-6. 


77 fkeys 




USAGE 


IS 


COMP-6. 


77 option 




USAGE 


IS 


COMP-6. 


77 do-it-yourse 


If 


USAGE 


IS 


C0MP-6 VALUE 1. 


77 user-window- 


1 ines 


USAGE 


IS 


C0MP-6. 


77 usei — window- 


columns 


USAGE 


IS 


COMP-6. 


77 user-window- 


id 


USAGE 


IS 


C0MP-6. 


77 create-seg 




USAGE 


IS 


COMP-6. 



77 bad-window- id 



USAGE IS COMP-6. 
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77 nonexistent-window USAGE IS COMP-6. 
77 insuff-room-for-wlndow USAGE IS COMP-6. 

PROCEDURE DIVISION. 

* The call to the cv_error_$name are used to collect -the code for 

* certain error messages that are of interest this application. 

* Once these codes are retrieved the occurrence of that error can 

* be easily tested for. 

START- IT. 
CALL "cv_error_$name" USING "video_et_$bad_window_id", 

bad-window-id, ret-code. 
IF ret-code EQUAL TO zero GO TO NEXT-ERR-CODE. 

CALL "com_err_" USING ret-code, me, " (calling cv error_$name) ". 
GO TO STOP- IT. 

NEXT-ERR-CODE. 
CALL "cv_error_$name" USING "video_et_$nonexistent_window", 

nonexistent-window, ret-code. 
IF ret-code EQUAL TO zero GO TO LAST-ERR-CODE. 

CALL "com_err_" USING ret-code, me , " (calling cv_error $name)". 
GO TO STOP- IT. 

LAST-ERR-CODE. 
CALL "cv_error_$name" USING "video_et_$insuff_room_for_window", 

insuff-room-for-window, ret-code. 
IF ret-code EQUAL TO zero GO TO SET-UP. 

CALL "com_err_" USING ret-code, me, " (calling cv_error_$name) ". 
GO TO STOP- IT. 

SET-UP. 
MOVE "Read Mail" TO choicesl (1) . 
MOVE "Send Mai 1" TO choicesl (2) . 

MOVE "Display Message" TO choices2(l). 

MOVE "Print Message" TO choices2(2). 
MOVE "Discard Message" TO choices2(3). 
MOVE "Forward Message" TO choices2(J»). 

MOVE "Reply Message" TO choices2(5). 

MOVE "List Messages" TO choices2(6). 

MOVE "Send New Message" TO choices3(l). 
MOVE "Send Deferred Message" TO choices3(2). 

MOVE "Print Sent Message" TO choices3(3). 

MOVE "Save Sent Message" TO choices3 (it) . 



MOVE "1" TO keys(l) . 

MOVE "2" TO keys (2) . 
MOVE "3" TO keys (3) . 

MOVE "k" TO keys (k) . 
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MOVE "5" TO keys (5) . 
MOVE "6" TO keys (6) . 

CALL "cb_menu_$initl". 

CALL "cb_menu_$ini t2" USING do-it-yourself, user-window-1 ines, 
user-window-columns, user-window- id, ret-code. 

* The call to cb_menu_$ i n i t 1 & 2 MUST be the first call to cb_menu_. 

* It sets up the appropriate environment for the menu application. 

* The application must do the window management, since 

* "do-i t-youself " is set to 1. 

IF ret-code EQUAL TO zero GO TO CREATE-F IRST-MENU. 
CALL "com_err_" USING ret-code, me, "Internal error. Could not set up 

appropriate environment.". 
GO TO STOP- IT. 

CREATE-F IRST-MENU. 

* Create first menu object. 

MOVE "Fl (or esc-q) = quit" TO trailers(l). 

MOVE "MULTICS MAIL" TO headers(l). 

CALL "cb_menu_$create" USING choices-tablel , headers-table, 

trailers-table, menu-format, keys-table, menu-needsl, 

menu-idl, ret-code. 

IF ret-code EQUAL TO zero GO TO CREATE-SECOND-MENU. 

CALL "com_err_" USING ret-code, me, " (calling cb_menu_$create) ". 

GO TO STOP- IT. 

CREATE-SECOND-MENU. 

* Create second menu object. 

MOVE "Fl (or esc-q) = quit; F2 (or esc-f) = first menu" TO trailers (1). 

MOVE "READ MAIL" TO headers(l). 

CALL "cb_menu_$create" USING choices-table2, headers-table, 

trailers-table, menu-format, keys-table, menu-needs2, 
menu-id2, ret-code. 
IF ret-code EQUAL TO zero GO TO CREATE-TH IRD-MENU. 
CALL "com_err_" USING ret-code, me, " (calling cb_menu_$create) ". 
GO TO STOP- IT. 

CREATE-TH IRD-MENU. 

* Create third menu object. 

MOVE "SEND MAIL" TO headers (1). 

CALL "cb_menu_$create" USING choices-table3, headers-table, 

trailers-table, menu-format, keys-table, menu-needs3, 

menu-id3. ret-code. 
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IF ret-code EQUAL TO zero GO TO STORE-MENU. 

CALL "com_err_ !! USING ret-code, me, " (calling cb_menu_$create) ". 

GO TO STOP- IT. 

STORE-MENU. 
MOVE ">udd>m>ri" TO dir-name. 
MOVE "menu_seg" TO entry-name. 
MOVE "cb_test_menu_" TO menu-name. 

MOVE 1 TO create-seg. 
CALL "cb_menu_$ store" USING dir-name, entry-name, menu-name, 

create-seg, menu-idl, ret-code. 
IF ret-code EQUAL TO zero GO TO DISPLAY- IT. 

CALL "com_err " USING ret-code, me, "(calling cb_menu_$ store) ". 
GO TO STOP-IT? 
DISPLAY-IT. 
MOVE -1 TO cur r -window-id. 

* Setting curr-wind-id to "-1" means that there is no current window 

* defined. 

MOVE menu-idl TO menu- id. 

MOVE 1 ines-neededl TO lines-needed. 

DISPLAY-FIRST-MENU. 

PERFORM CHANGE-MENU THRU GOBACK. 

* The user i/o window has been "shrunk", the window for the first menu 

* has been created, and the first menu has been displayed. 

MOVE window-id TO window-idl. 
IF ret-code EQUAL TO zero GO TO GET-iT. 
CALL "com_err_" USING ret-code, me, "Internal error. 

Menu could not be displayed." 
GO TO STOP- IT. 

GET-IT. 
PERFORM GET-CHOICE. 

* Get the user input. Two values are returned. (1) fkey. If fkey = 1, 

* then the user entered a function key (or its equivalent escape 

* sequence). If fkey = then the user has selected an option. (2) option, 

* If fkey = 1 then option is the function key number entered. (Fl = 1, 

* F2 = 2, etc.). If fkey = 0, then option is the option number selected, 

* option = 1 means option 1 selected, etc. 

IF ret-code EQUAL TO zero GO TO TEST-FKEY. 

CALL "com_err_" USING ret-code, me, "Internal error. 

While getting user's choice.". 
GO TO STOP- IT. 
TEST-FKEY. 
IF fkeys EQUAL TO 1 

IF option EQUAL TO 1 
CALL "ioa " USING "Exiting at your request." 
GO TO STOP- IT 
ELSE 

GO TO GET- IT 
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ELSE 

IF option EQUAL TO 1 
MOVE menu-id2 TO menu- id 

MOVE 1 ines-needed2 TO lines-needed 
PERFORM CHANGE-MENU THRU GOBACK 
ELSE 

MOVE menu-id3 TO menu- id 
MOVE 1 ines-needed3 TO lines-needed 
PERFORM CHANGE-MENU THRU GOBACK. 
IF ret-code NOT EQUAL TO zero 
CALL "com_err_" USING ret-code, me, "Internal error. 

While trying to display menu." 
GO TO STOP- IT 
ELSE 

MOVE window- id TO window- id2. 
NEXT-GET-IT. 
PERFORM GET-CHOICE. 

IF fkeys EQUAL TO zero GO TO CHOSE-OPTION. 
IF option EQUAL TO 1 
CALL "ioa_" USING "Exiting at your request." 
GO TO STOP- IT 
ELSE 

IF option GREATER 2 

GO TO NEXT-GET- IT 
ELSE 

MOVE menu-idl TO menu- id 
MOVE i ines-neededl TO lines-needed 
GO TO DISPLAY-FIRST-MENU. 
CHOSE-OPTION. 
CALL "ioa_" USING "You chose option ~d.", option. 
GO TO NEXT-GET- IT. 

GET-CHOICE. 
CALL "cb_menu_$get_choice" USING window-id, menu-id, 
function-key-info, fkeys, option, ret-code. 

CHANGE-MENU. 

* Destroy the current menu window. 
IF (curr-window-id ) EQUAL TO -1 GO TO CHANGE-USER-WIND. 
CALL "cb_window_$destroy" USING curr-window-id, ret-code. 

IF ret-code EQUAL TO zero GO TO CHANGE-USER-WIND. 
GO TO GOBACK. 

CHANGE-USER-WIND. 
COMPUTE first- line = lines-needed + 1. 
COMPUTE height = user-window- 1 ines - lines-needed. 
CALL "cb_window_$ change" USING user-window- id, first-line, height, 

ret-code. 
IF ret-code EQUAL TO zero GO TO CREATE-NEW-WIND 
ELSE GO TO GOBACK. 
CREATE-NEW-WIND. 
MOVE "menu-window" TO switch-name. 
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MOVE 1 TO first- line. 
CALL "cb_window_$create" USING first- line, lines-needed, 

switch-name, window- id, ret-code. 
IF ret-code EQUAL TO zero GO TO DISPLAY-MENU 
ELSE GO TO GOBACK. 
DISPLAY-MENU. 

MOVE window- id TO cur r -window-id. 
CALL "cb_menu_$di splay" USING window-id, menu-id, ret-code. 

CALL "cb_window_$clear_window" USING user-window-id, ret-code. 

GOBACK. 
EXIT. 

STOP- IT. 
CALL "cb_menu_$terminate". 

* cb_menu_$terminate MUST be the last call to cb_menu_ in the 

* application. It terminates the environment set up cb_menu_$ i n i t . 

EXIT PROGRAM. 
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This appendix reviews the standard I/O switch attachments, then describes how these 
attachments change when you activate the video system on your terminal and create a menu. 

There are four standard switches which are attached when your process is created. These 
switches are as follows: 

(1) user_i/o: this switch acts as a common collecting point for all terminal I/O. It's 
attached to your terminal through the I/O module tty_, and is opened for stream 
input and output 

(2) user_input this switch controls command and data input at your terminal. It's 
attached to user_i/o through the I/O module syn_, and through that to your terminal. 
It's opened for stream input. 

(3) user_output: this switch controls command and data output at your terminal. It's 
attached to user_i/o" through the I/O module syn_, and through that to your terminal. 
It's opened for stream output. 

(4) error_output: this switch controls output of error messages at your terminal. It's 
attached to user_i/o through the I/O module syn_, and through that to your terminal. 
It's opened for stream output 

To get information about I/O switch attachments, you can use the print_attach_table 
(pat) command. If you type "pat" on your terminal right after you log in, the system will 
print the following: 

error_output syn_ user_i/o -inh close get_line get_chars 
user_input syn_ user_i/o -inh close put_chars 
user_i/o tty_ -logi n_channel 

stream_i nput_output 
user_output syn_ user_i/o -inh close get_line get_chars 
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You can see from this that user_input, user_output, and error_output are all attached 
via syn_ to user_i/o, which in turn is attached via tty_ to your terminal. Figure A-l 
illustrates these standard I/O switch attachments. 

When you activate the video system, by issuing a call to video_utils_$turn_on_login_channel 
or by executing the window_call invoke command, the existing tty_ attachment of your 
terminal is removed and replaced with video system attachments. The I/O switch user_i/o is 
now attached through the I/O module window_io_ to a new I/O switch, user_terminal_. 
User_terminal_ is attached through the I/O module tc_io_ to your terminal. 
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Figure A-l. Standard Attachments 
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If you type "pat" on your terminal after invoking video, the system will print the 
following: 

user_terminal_ tc _'°_ -login_channel 

stream_i nput_output 
error_output syn_ user_i/o -inh close get_line get_chars 
user_input syn_ user_i/o -inh close put_chars 
user_i/o window_io_ user_terminal_ -first_line 1 -n_lines 2k 

stream_input_output Video 
user_output syn_ user_i/o -inh close get_line get_chars 



You can see from this that user_input, user_output, and error_output are still attached 
via syn_ to user_i/o, but that user_i/o is now attached via window_io_ to user_terminal_, 
which is in turn attached via tc_io_ to your terminal. User_i/o is now a window as well as 
a switch. It begins on line 1 of your screen and is 24 lines long. On a VIP7801 terminal, 
this means that the window covers the entire screen. Figure A-2 illustrates these changes to 
the standard I/O switch attachments. 

When you execute an exec_.com to create a menu, the necessary attachments for your 
menu are built on top of those already set up by your activation of the video system. If 
you run the exec_com discussed in Section 3 (doc_sys.ec), then type "pat" on your terminal, 
the system will print the following: 

user_terminal_ tc_io_ -logi n_channel 

stream_input_output 
error_output syn_ user_i/o -inh close get_line get_chars 
user_input syn_ user_i/o -inh close put_chars 
user_i/o window_io_ user_terminal_ -first_line 8 -n_lines 17 

stream_input_output Video 
user_output syn_ user_i/o -inh close get_line get_chars 
! BBBJLXDqDbMNnn.menu 

window_io_ user_termi nal_ -first_line 1 -n_lines 7 

stream_input_output Video 

8 1 1 007 1M650 . 6 1 3707 . exec_com 

ec_input_ ">udd>Project>Person>doc_sys.ec" stream_input 
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You can see from this that user_input, user_output, and error_output are still attached 
via syn_ to user_i/o, that user_i/o is still attached via window_io_ to user_terminal_, and 
that user_terminal_ is still attached via tc_ic_ to your terminal. But in addition, the 
:BBBJLXDqDbMNnn.menu is now attached through window_io_ to user_terminal_ also. ' (The 
unique character string "IBBBJLXDqDbMNnn" is generated by using the unique active function, 
as in the construction [unique] .menu, used in doc_sys.ec.) The user_i/o window still begins 
on line 1. but now it is only 7 lines long. The !BBBJLXDqDbMNnn.menu, which, like 
user_i/o, is a window as well as a switch, begins on line 8, and is 17 lines long. 

The last two lines printed above provide information about attachments made to 
support the execution of the exec_com. They are of no concern to you in this discussion. 
Figure A-3 illustrates I/O switch attachments after the video system has been activated and 
an exec_com creating a menu has been run. 

For more information on the print_attach_table command and the unique active 
function, refer to the Multics Commands and Active Functions manual, Order No. AG92. 
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Figure A-2. Attachments After the Invocation of Video 
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Figure A-3. Attachments After Execution of doc_sys.ec exec_com 
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The subroutine cv_error_$name is provided in order to allow the FORTRAN and 
COBOL programmer to test return codes in a way similar to that provided by PL/I. 

It provides a means to associate an error "name", e.g., "menu_et_$too_few_keys" with 
the numeric value of the returned code. Once this is done the programmer can test for a 
given error code by using the name associated with it 

SYNTAX IN FORTRAN 

call cv_error_$name (error_name, converted_code, code) 

SYNTAX IN COBOL 

CALL "cv_error_$name" USING error-name, converted-code, ret-code. 

ARGUMENTS 

error_name (error-name) 

a quoted string, e.g., "menu_et_$too_many_options", which is name of the error. (Input) 

converted_string (converted-string) 

an integer (USAGE IS COMP-6 in COBOL) variable where the returned numeric value 
of the code is to be stored. (Output) 

code (FORTRAN) 

if call was successful, nonzero otherwise, (integer) (Output) 

ret-code (COBOL) 

if call was successful, nonzero otherwise. (USAGE IS COMP-6) (Output) 

NOTES 

"code" must be declared as "integer" in a FORTRAN program and "ret-code" as USAGE IS 
COMP-6 in a COBOL program. In every call, to any entry point defined in this document, 
a return code of zero always means that the call was executed successfully.) 



B-l CP51-02 



Error codes of particular interest are: 

menu_et_$too_many_options 

(A menu can contain at most 61 choices.) 

menu_et_$too_few_keys 

(There are fewer keys than choices.) 

menu_et_$keys_not_unique 

(Each key must be unique.) 

menu_et_$higher_than_max 

(The menu will not fit within the specified maximum height) 

video_et_$bad_window_id 

(The supplied window id was not valid.) 

video_et_$overlapping_windows 

(Two windows may not overlap on the screen.) 

video_et_$window_too_big (The screen is too small to accommodate a window of the 
requested size.) 

video_et_$insuff_room_for_window 

(Insufficient room to create window.) 

video_et_$window_too_small 

(Tried to adjust window past minimum size.) 

video_et_$negative_screen„size 

(Negative screen size specified.) 

video_et_$negative_window_size 

(Negative window size specified.) 

video_et_$nonexistent_window 

(Specified window does not exist) 

video_et_$overlaps_other_window 

(Specified window overlaps other windows.) 

video_et_$unable_to_create_window 
(Unable to create window.) 

video_et_$unable_to_dest_window 

(Unable to destroy window.) 

video_et_$switch_not_window 

(The specified switch is not attached as a window.) 

error_table_$no_operation 

(Cannot call this entry point in your current mode. Requested operation could not be 
performed.) 



B-2 CP51-02 



INDEX 



MISCELLANEOUS 



~A i»-5 

~B k-k 

~D 4-5 

~E 4-5 

~L 4-4 

~Q 4-4 

~Y 4-3 

# 4-5 



arguments for window_call 
bell 5-ii 

change_window 2-12, 5" 12 
clear_region 5~12 
clear_to_end_of_l ine 5"12 
clear_to the_end of_window 

5-13 
clear_window 2-13. 5~ 13 
create window 2-9. 5~ 13 



arguments for window_call 
(cont) 
delete_chars 5"14 
delete_window 2-12, 5"14 
get_echoed_chars 5" 14 
get_f irst_l ine 5" 15 
get_one_unechoed_char 5" 15 
get_position 5" 15 
get_terminal_height 5" 16 
get_terminal_width 5"16 
get_unechoed_chars 5" 16 
get_window_height 5~17 
insert text *»~ 17 
invoke 2-9, 5" 17 
overwri te_text 5" 18 
revoke 5" 18 
scrol l_region 5 - 18 
set_position 5" 19 
set_posi tion_rel 5 - 19 
supported_terminal 5" 19 
sync 5-19 
video_ invoked 5" 20 
wr i te_sync_read 5"20 

attaching video system 2-5 

attachments 
review of 

see also video attachments 
see standard attachments 
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COBOL interface 9-1 



backspace key J+-2 

backward character 
~B k~k 

backward word 
ESC B k-5 

beginning 1 ine 
"A k-5 



capitalize initial word 
ESC C k-5 

capital ize word 
ESC U k-5 



cb_menu_ 
cb_menu_ 
cb_menu_ 
cb_menu_ 
cb_menu_ 
cb_menu_ 
cb_menu_ 
cb_menu_ 
cb_menu_ 
cb_menu 
cb_menu_ 
cb_menu_ 
cb menu 
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$create 9-2 
$delete 9~5 
$describe 9"5 
$destroy 9"6 
$display 9 _ 7 
$get_choice 9 _ 8 
"$i ni tl 9-9 
$init2 9~9 
'$ 1 i s t 9-10 
$retrieve 9-11 
$store 9-12 
$terminate 9 - 13 



cb_window_ 3~\k 

cb_window_$change 3~\k 
cb window_$clear_window 

9-15 
cb_window_$create 9" 15 
cb_window_$destroy 9- 16 

clear and redisplay 
ESC ~L k-k 



control characters 
backward character 

~B k-k 
backward word 

ESC B k-5 
beginning line 

"A k-5 
capitalize initial word 

ESC C k-5 
capital ize word 

ESC U k-5 
clear and redisplay 

ESC ~L k-k 
delete character 

"D k-5 
delete word 

ESC D k-5 
end of 1 i ne 

~E k-5 
erase k~2 

backspace key k~2 

DEL, # k-5 
erase word 

ESC DEL, ESC # k~5 
forward character 

"F k-k 
forward word 

ESC F k-k 
kill k-2 
lower case word 

ESC L k-5 
quoting character 

-Q k-k 
real-time editor 1*— 1 
redisplay 

"L k-k 
retrieving deleted text 

ESC Y k~3 

A Y i»-3 
twiddle word 

ESC T k-5 
two characters l»-2 

deleting words l»-2 

retrieving deleted text 
4-3 



clear window example 2-13 



create_window example 2-10 
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data structures 
menu_format 6-8 
menu_t i st_tnfo 6~9 
menu_requirements 6~11 

DEL if-5 

delete character 
~D i»-5 

delete word 
ESC D i»-5 

delete_window example 2-12 

deleting words 4-2 

detaching video system 2-7 



end of 1 i ne 
A E k-5 

end of window processing 4- 10 

erase character 4 _ 2 

# 4-5 

backspace key k~2 

DEL 4-5 

erase word 

ESC DEL, ESC # 4~5 

error_output switch A-l 

ESC # 4-5 

ESC B 4-5 

ESC C 4-5 

ESC D 4-5 



ESC DEL 4-5 
ESC F 4-4 
ESC L 4-4, 4-5 
ESC T 4-5 
ESC U 4-5 
ESC Y 4-3 

examples 

exec_com 

attaching video 2-5 
clear_window 2-13 
create_window 2-10 
delete_window 2-12 
detaching video 2~7 
document system 3^2 

function keys 3"1 

function keys alternative 
3-1 

pll 

attaching video 2-6 
detaching video 2-7 
document system 3~6 
window_$clear_window 2-13 
w!ndow_$create 2-ii 
wi ndow_$destroy 2-12 

extensions 

writing editor 4~5 



forward character 
~F 4-4 

forward word 
ESC F 4-4 

ft_menu_ 8" 2 

f t_menu_$create 8*2 
f t_menu_$delete 8~4 
f t_menu_$descr ibe 8 - 4 
f t_menu_$destroy 8 - 5 
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ft_menu_ (cont) 

ft_menu_$di splay 8~6 
ft_menu_$get_choice 8 _ 6 
ft_menu_$ini tl 8~8 
f t~menu~$ i n i t2 8~8 
ft_menu_$retrieve 8" 10 
ft_menu_$ store 8" 10 
ft_menu_$ terminate 8 _ 1 1 

ft_window_ 8-13 

ft_window_$change 8 _ 13 
ft window_$clear_window 

8-H 
ft_window_$ create 8 _ U» 
ft_window_$ destroy 8" 15 

function keys 

alternatives 3"2 

guidel ines for 3 _ 1 

recommendations 3 - 2 

ttt info_$function_key_data 

" 3-1 



I/O modules 
tc_io_ 7-2 
window io 7"5 



K 

kill character k-2 
kill ring 1»~3 



lower case word 
ESC L k-5 



M 



menu 

definition 1-1 
games example 1-1 
managerial example l~k 
manual orders example 1-3 
Multics tutorial example 

1-3 
programming example 1-5 

menu and video 

connection between 1-5 

menu commands 
menu_create 5"2 
menu_delete 5" h 
menu_describe 5~5 
menu_di splay 5 _ 6 
menu_get_choice 5"7 
menu_l i st 5"9 

menu_ 6"2 

menu_$create 6-2 
menu_$delete 6~3 
menu_$descr i be d~k 
menu_$destroy 6-1* 
menu_$di splay 6"5 
menu_$get_choice 6 _ 5 
menu_$list 6~6 
menu_$retrieve 6"7 
menu_$store 6 _ 8 

menu_create command 5"2 

menu_delete command S~h 

menu_descr i be command 5"5 

menu_di splay command 5"6 

menu_format data structure 
6-8 

menu_get_choice command 5"7 
menu list command 5"9 
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menu_l ist_info data structure 
6-9 

menu_requi rements data 
structure 6 _ 11 

miscellaneous capabilities 
in windows 2-4 

MORE processing 4- if 4" 10 



operations 

on windows 2-8 

change_window 2-12 
clear_window 2-13 
create_window 2-9 
set_window_info 2-12 

output buffering if- 11 

output control 4-1 

overlap rule for windows 2-8 



real-time editor 4-1 
control characters 1»— 1 
deleting words 4-2 
erase and kill values 4~1 
erase character I+-2 
kill character i»-2 
retrieving deleted text 4—3 

redisplay 

requirements for windows 2-8 

retrieving deleted text 1» — 3 
ESC Y 1,-3 
"Y k-5 

routines 

1 ine editor 4 _ 6 



scrol 1 ing 



positioning the cursor 
in windows 2-3 

pr int_attach_table description 
see the Commands manual 



quoting character 



selective alteration 
in windows 2-4 

selective erasure 
in windows 2-4 

standard attachments A-l 
after invoking video A-4 
i 1 lustration of A-3 
via syn_ A-2 
via tty_ A-2 

standard I/O switch A-l 

standard I/O switch 
attachments 
see also standard 
attachments 
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standard switch names 
error_output A-l 
user_input A-l 
user_io switch A-l 
user_output A-l 

switch attachments 

see also video attachments 
see standard attachments 



user_io window 2-5. 2-9. 2-12, 
2-13. 3-2 
size of 2-5 

user_output switch A-l 

uti 1 ities 

window editor i*-8 



syn_ 

see the Subroutines manual 



tc_io_ 7-2 

attach description 7"2 
control operations 
clear_screen 7 _ 3 
get_break_table 7~3 
get_capab i 1 i t i es 7 _ 3 
reconnect ion l~k 
set_break_table 7 - 3 
set_l i ne_speed 7 - 3 
set_term_type J-k 
get line operation 7"3 
open operation 7"3 

trailer lines 2-8 



tty_ 

see the Subroutines manual 



twiddle word 
ESC T k-5 



unique active function 
see the Commands manual 

user_input switch A-l 

user io switch A-l 



video and menu 

connection between 1-5 

video attachments A-2 
after exec_com execution 

A-l* 
i 1 lustration of A-6 
tc_io_ A-l» 
via window_io_ A-l» 

video command 

window_call 5 _ 10 

video subroutines 
video_data_ 6~12 
v i deo_da ta_$ term i na 1 _i ocb 

6-12 
video_utils_ 6~13 
video_uti ls_$ 

tur n_of f _1 og i n_channe 1 

6-H 
turn_on login_channel 2-9. 

6-T3 
window_ 6-15 
w i ndow_$ 

clear_to_end of_window 

6-18 
get one_unechoed_char 

6-21+ 
window_$bell 6~15 
window_$change_column 6 - 16 
wi ndow_$change_l i ne 6-16 
window_$clear_region 6~17 
wi ndow_$clear_to_end_of_l i ne 

6-18 
window_$clear_window 6~19 
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video subroutines (cent) 

window_$clear_window example 
2-13 

window_$create 6-19 
window_$ create example 2-11 
w i ndow_$del ete_char s 6-20 
window_$destroy 6~21 
window_$destroy example 

2-12 
w i ndow_$ed i t_l i ne 6-2 1 
w i ndow_$get_cur sor_pos i t i on 

6-22 
window $get_echoed chars 

6-23 
window $get_unechoed_chars 

6-25 
window_$insert_text 6-26 
window_$overwrite_text 6~26 
window $posi tion_cursor 

6 r 27 
window_$position_cursor rel 

6-27 
window_$seron_region 6-28 
window_$sync 6-29 
window_$write_raw_text 6"29 

video system 
attaching 2-5 
command interface 4- 11 
detaching 2-7 
features i*- 1 

end of window processing 
4-10 

MORE processing 1,-1, 4-10 

output control 1,-1 

real-time editing 1,-1 

windows 2-1 
subroutine interface 1,-11 
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w i ndow 

w i ndow_ed i tor_ut i 1 s_$ 
backward 4-9 
backward_word 1,-9 
delete_text 1,-8 
delete_text_save 4-9 



window (cont) 

wi ndow_ed i tor_ut i 1 s_$ 

get_top_k ill r i ng_e 1 ement 

4~9 
insert_text 4-JL 
move_backward word 4-9 
move_forward 4-9 
move_forward word 4-9 
rotate_ki 1 l_ring 4- 10 

w i ndows 

definition 2-1 
height of 2-9 
miscellaneous capabilities 

2-4 
naming of 2-9 
number permitted 2-8 
operations 2-1, 2-8 

change_window 2-12 

clear_window 2-1 3 

create_window 2-9 

set_window_info 2-12 
overlap rule 2-8 
positioning cursor 2-3 
requirements 2-8 
scrolling 2-4 
selective alteration 2-4 
selective erasure 2-4 
trailer lines 2-8 
width of 2-8 

window_ 4-11, 6~15 
window_$ 

c 1 ear_to_end_of _w i ndow 

6-18 
get_one_unechoed_char 
6-24 
window_$bell 6~15 
window_$change_column 6-16 
window_$change_l ine 6~16 
window_$clear_region 6~17 
w i ndow_$c 1 ear_to_end_of _ 1 i ne 

6-18 
window_$clear_window 6~19 

example 2-13 
window_$ create 6 - 19 

example 2-11 
window_$delete_chars 6-20 
window_$destroy 6~21 
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window_ (cont) 
window_$destroy 
example 2-12 
window_$edit_l ine 6-21 
window_$get cursor_posi tion 

6-22 
window_$get echoed_chars 

6-23 
window $get unechoed_chars 

6 r 25 
window_$insert_text 6-26 

window_$overwr i te_text 6~26 

wi ndow_$pos i t i on_cur sor 

6-27 
wi ndow_$pos i t i on_cursor_rel 

6-27 
window_$scroll_region 6*28 

window_$sync 6~29 
window~$write_raw_text 6~29 
wi ndow_$wr i te_sync_read 
6-30 
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indow cal 1 it— 1 1 



window_call arguments 
see arguments for 
window_cal 1 

window_call command 5" 10 

window_io_ 7"5 

attach description 7"5 

control operations 

get_break_table 7" 15 
get_capab i 1 i t i es 7"9 
get~editing_chars 7" 10 
get_more_responses 7"H 
get_output conversion 

7-16 ~ 
get_special 7" 16 
get_token_characters 7"20 
get_window_info 7 "7 
get_window_status 7 _ 8 
reset_more 7" 10 
set_break_table 7" 15 
set~editing_chars 7" 10 
set_more_responses 7 - H 
set_output_conversion 

7-16 



w i ndow_ i o_ (cont) 

control operations 
set_special 7" 17 
set_token_characters 
set_window_info 7"7 
set_window_status 7"8 

control operations from 
command level 7 "26 

get chars operation 7 - 6 

get line operation 7"6 

modes operations 
can, "can 7 _ 25 
ctl_char, "ctl_char 
erkl, "erkl 7~25 
esc, "esc 7"26 
11 7-26 

more, '"more T~2k 
more_mode 7"2i» 

pi 7-26 

rawi, "rawi 7~26 
rawo, "rawo 7'25 
red, "red 7~26 
vertsp, 'Vertsp 7~25 
open operation 7"6 
put chars operation 7~6 
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